The Battle for Wesnoth Wiki - User contributions [en]

AnimationWML

2014-02-15T22:52:04Z

Coffee: introduction to psuedo code change

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

* a '''plain string''' — e.g., “abc” or “123”;
* a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
* a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

Ranges can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be '''backward''' — from a greater number to a lesser number (e.g., “5~1”).

===== Range expansion =====

Each '''range''' ''<var>x</var>~<var>y</var>'' is expanded within its expansion list to a comma-separated list of radix-10 integers (which are plain strings), starting from the first endpoint <var>x</var> and ending at the second endpoint <var>y</var>.

If '''<var>x</var> < <var>y</var>''', then the numbers in this list increase by increments of 1; if '''<var>x</var> > <var>y</var>''', then the numbers in this list decrease by decrements of 1. E.g., “1~3” would become “1,2,3”, and “3~1” would become “3,2,1”.

If '''<var>x</var> = <var>y</var>''', then this list has only one element, which is <var>x</var> (and is also <var>y</var>, of course). E.g., “2~2” would becomes “2”.

If either <var>x</var> or <var>y</var> (or both) are padded with '''leading zeros''', then each number in the resultant list will be padded with leading zeros such that it is expressed in at least <var>z</var>+1 digits, where <var>z</var> is the quantity of leading zeros with which one or both endpoints are padded. E.g.,
* “07~11” would become “07,08,09,10,11”,
* “098~100” would become “98,99,100”,
* “003~1” (or “3~001”) would become “003,002,001”, and
* “0098~100” would become “098,099,100” (although poor form), and
* “01~100” would become “01,02,...,10,11,...,999,100”.

If both endpoints are padded with leading zeros, they should both be padded with the same quantity of leading zeros.

===== Repetition expansion =====

Each '''repetition''' ''<var>s</var>*<var>n</var>'' is expanded within its expansion list to a comma-separated list with <var>n</var> elements, each of which is the string <var>s</var>. E.g., “abc*3” would become “abc,abc,abc”.

===== Square bracket expansion =====

A single '''progressive string value''' may contain multiple '''square-bracketed expansion lists''', which must all be of the same length in elements (after range and repetition expansion). This length shall be referred to as <var>L</var> for the remainder of this section.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list with <var>L</var> elements.

For each integer <var>n</var> from 1 to <var>L</var>, the <var>n</var>-th element of this list shall be a copy of the progressive string, with each expansion list it contains replaced with that expansion list’s <var>n</var>-th element (after range and repetition expansion).

When a progressive string that contains expansion lists is processed it is transformed at each bracket pair into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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.

Note that xxx_ parameters (e.g. missile_offset) are shortcuts to access parameters from outside of their corresponding frame and have no effect inside of them.

== How animations are chosen ==
Within a unit description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-15T22:43:02Z

Coffee: square bracket headers down one level

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

* a '''plain string''' — e.g., “abc” or “123”;
* a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
* a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

Ranges can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be '''backward''' — from a greater number to a lesser number (e.g., “5~1”).

===== Range expansion =====

Each '''range''' ''<var>x</var>~<var>y</var>'' is expanded within its expansion list to a comma-separated list of radix-10 integers (which are plain strings), starting from the first endpoint <var>x</var> and ending at the second endpoint <var>y</var>.

If '''<var>x</var> < <var>y</var>''', then the numbers in this list increase by increments of 1; if '''<var>x</var> > <var>y</var>''', then the numbers in this list decrease by decrements of 1. E.g., “1~3” would become “1,2,3”, and “3~1” would become “3,2,1”.

If '''<var>x</var> = <var>y</var>''', then this list has only one element, which is <var>x</var> (and is also <var>y</var>, of course). E.g., “2~2” would becomes “2”.

If either <var>x</var> or <var>y</var> (or both) are padded with '''leading zeros''', then each number in the resultant list will be padded with leading zeros such that it is expressed in at least <var>z</var>+1 digits, where <var>z</var> is the quantity of leading zeros with which one or both endpoints are padded. E.g.,
* “07~11” would become “07,08,09,10,11”,
* “098~100” would become “98,99,100”,
* “003~1” (or “3~001”) would become “003,002,001”, and
* “0098~100” would become “098,099,100” (although poor form), and
* “01~100” would become “01,02,...,10,11,...,999,100”.

If both endpoints are padded with leading zeros, they should both be padded with the same quantity of leading zeros.

===== Repetition expansion =====

Each '''repetition''' ''<var>s</var>*<var>n</var>'' is expanded within its expansion list to a comma-separated list with <var>n</var> elements, each of which is the string <var>s</var>. E.g., “abc*3” would become “abc,abc,abc”.

===== Square bracket expansion =====

A single '''progressive string value''' may contain multiple '''square-bracketed expansion lists''', which must all be of the same length in elements (after range and repetition expansion). This length shall be referred to as <var>L</var> for the remainder of this section.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list with <var>L</var> elements.

For each integer <var>n</var> from 1 to <var>L</var>, the <var>n</var>-th element of this list shall be a copy of the progressive string, with each expansion list it contains replaced with that expansion list’s <var>n</var>-th element (after range and repetition expansion).

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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.

Note that xxx_ parameters (e.g. missile_offset) are shortcuts to access parameters from outside of their corresponding frame and have no effect inside of them.

== How animations are chosen ==
Within a unit description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-15T22:37:09Z

Coffee: AI0867 updated documentation

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

* a '''plain string''' — e.g., “abc” or “123”;
* a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
* a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

Ranges can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be '''backward''' — from a greater number to a lesser number (e.g., “5~1”).

==== Range expansion ====

Each '''range''' ''<var>x</var>~<var>y</var>'' is expanded within its expansion list to a comma-separated list of radix-10 integers (which are plain strings), starting from the first endpoint <var>x</var> and ending at the second endpoint <var>y</var>.

If '''<var>x</var> < <var>y</var>''', then the numbers in this list increase by increments of 1; if '''<var>x</var> > <var>y</var>''', then the numbers in this list decrease by decrements of 1. E.g., “1~3” would become “1,2,3”, and “3~1” would become “3,2,1”.

If '''<var>x</var> = <var>y</var>''', then this list has only one element, which is <var>x</var> (and is also <var>y</var>, of course). E.g., “2~2” would becomes “2”.

If either <var>x</var> or <var>y</var> (or both) are padded with '''leading zeros''', then each number in the resultant list will be padded with leading zeros such that it is expressed in at least <var>z</var>+1 digits, where <var>z</var> is the quantity of leading zeros with which one or both endpoints are padded. E.g.,
* “07~11” would become “07,08,09,10,11”,
* “098~100” would become “98,99,100”,
* “003~1” (or “3~001”) would become “003,002,001”, and
* “0098~100” would become “098,099,100” (although poor form), and
* “01~100” would become “01,02,...,10,11,...,999,100”.

If both endpoints are padded with leading zeros, they should both be padded with the same quantity of leading zeros.

==== Repetition expansion ====

Each '''repetition''' ''<var>s</var>*<var>n</var>'' is expanded within its expansion list to a comma-separated list with <var>n</var> elements, each of which is the string <var>s</var>. E.g., “abc*3” would become “abc,abc,abc”.

==== Square bracket expansion ====

A single '''progressive string value''' may contain multiple '''square-bracketed expansion lists''', which must all be of the same length in elements (after range and repetition expansion). This length shall be referred to as <var>L</var> for the remainder of this section.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list with <var>L</var> elements.

For each integer <var>n</var> from 1 to <var>L</var>, the <var>n</var>-th element of this list shall be a copy of the progressive string, with each expansion list it contains replaced with that expansion list’s <var>n</var>-th element (after range and repetition expansion).

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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.

Note that xxx_ parameters (e.g. missile_offset) are shortcuts to access parameters from outside of their corresponding frame and have no effect inside of them.

== How animations are chosen ==
Within a unit description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T02:48:36Z

Coffee: Add pseduo code

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

All bracketed lists in the same progressive string within comma separation must have the same length (after ranges are expanded), and the result is a series of that many images.

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

# a plain '''string''' — e.g., “abc” or “123”;
# a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
# a '''range''', where zero padding is preserved, otherwise as above — e.g., “01~10”; or
# a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

'''Ranges''' can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be backward — from a greater number to a lesser number (e.g., “5~1”).

A single progressive string value may contain multiple expansion lists, which must all be of the same length in elements.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T02:39:20Z

Coffee: /* Progressive string square bracket expansion syntax */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

All bracketed lists in the same progressive string within comma separation must have the same length (after ranges are expanded), and the result is a series of that many images.

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

# a plain '''string''' — e.g., “abc” or “123”;
# a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
# a '''range''', where zero padding is preserved, otherwise as above — e.g., “01~10”; or
# a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

'''Ranges''' can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be backward — from a greater number to a lesser number (e.g., “5~1”).

A single progressive string value may contain multiple expansion lists, which must all be of the same length in elements.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list, which is generated as follows:

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T02:38:07Z

Coffee: Separate square bracket expansion into new subtopic

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

All bracketed lists in the same progressive string must have the same length (after ranges are expanded), and the result is a series of that many images.

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

# a plain '''string''' — e.g., “abc” or “123”;
# a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
# a '''range''', where zero padding is preserved, otherwise as above — e.g., “01~10”; or
# a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

'''Ranges''' can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be backward — from a greater number to a lesser number (e.g., “5~1”).

A single progressive string value may contain multiple expansion lists, which must all be of the same length in elements.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list, which is generated as follows:

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

SoC People to bug on IRC

2014-02-08T02:05:26Z

Coffee: Add mention of Boucman to animation code

{{SoC2014}}

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

=== Coffee ===
Involved mostly in the animation coding and minor bugfixes, Coffee can help with coding questions surrounding unit animations. Boucman is also a good source for animation code, although currently an inactive developer.

=== Crab_ ===
iurii chernyi (Crab) has joined the team in 2009. He restructured Wesnoth AI as part of GSoC-2009, and is an expert on all aspects of current Wesnoth AI codebase. So, he's the person to ask about anything in '''src/ai'''. He also knows much about campaign units/leaders persistence.

=== happygrue/Wintermute ===

Has been involved with multiplayer balance and testing for a number of years. Currently working on balancing the default+khalifate era, but interested in, and often available for, testing various aspects game play or mechanics. A good person to bug about getting feedback from the multiplayer community about any relevant issue.

=== loonycyborg ===
Maintainer of Wesnoth's SCons build system and windows packager. Might also help out with other buildsystems.

=== mattsc ===

Has no computer science background and doesn't really know much about how coding should be done, but has been fiddling with Wesnoth AI behavior for a while now, accumulating some empirical experience along the way. He might be able to help with questions on AI behavior and, to a lesser extent, on AI functionality.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Mordante is currently busy rewriting the old gui engine, he will be our expert there as well as already being our area expert for the terrain engine. He also has limited experience with boost asio.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area.

=== shadowm ===
He has been around since late 2007, and has worked in many areas of the game, including WML event commands handling, image path functions, and the add-ons client code. As an add-on content developer, he also knows a lot about the WML language itself (preprocessor, syntax) and the functionality available in single-player campaigns.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== vultraz ===
He can assist with questions related to the Lua GUI2 bindings and their usage.

=== zookeeper ===
Has been around for a long time and has at least a passing familiarity with most things outside the engine code, music and Lua. Maintains a large part of the mainline campaigns and knows the WML language well. Can be contacted when it comes to anything related to WML, gameplay and scenario design, or the mainline content in general.

== Inactive people ==

These people are currently not actively participating in development and are likely not available to help. You can always try, of course. They may also not be entirely up-to-date regarding their areas of expertise anymore.

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Dragonking ===

He is one of our best Wesnoth players, and understands the various strategies well. He has also programmed much of the Wesnoth Formula AI system and understands it well.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== Gabriel Morin (gabba) ===

gabba joined the team in 2010 where he participated in GSoC, and is the conceptor and maintainer of Wesnoth's planning system, codenamed "Whiteboard".

=== ilor ===
2008 GSoC student, worked on and maintains the new map editor in Wesnoth 1.5/1.6/1.7. Has some fairly recent experience with getting "in" the Wesnoth codebase.

=== Karol Nowak (grzywacz) ===
Two years he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on Wesnoth for embedded devices as he worked on the gp2x support.

=== Sapient ===
This developer started working on the GUI and widgets, but recently he focused more on improving the internal mechanics of the WML engine such as variable look-ups and filtering. Sapient is not as active anymore but he does come one IRC in the evenings (U.S.A.). He has touched-up many areas of the code in small ways over time, thus he has a good general knowledge of the C++ code and also has worked a little on some python maintenance scripts.

=== YogiHH ===
Since he is the developer who know most about building under Windows, he will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.
YogiHH also knows quite a bit about the game engine and everything that has to do with replays and savegames.

=== Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

SoC People to bug on IRC

2014-02-08T01:55:54Z

Coffee: Add myself to list (Coffee)

{{SoC2014}}

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

=== Coffee ===
Involved mostly in the animation coding and minor bugfixes, Coffee can help with coding questions surrounding unit animations.

=== Crab_ ===
iurii chernyi (Crab) has joined the team in 2009. He restructured Wesnoth AI as part of GSoC-2009, and is an expert on all aspects of current Wesnoth AI codebase. So, he's the person to ask about anything in '''src/ai'''. He also knows much about campaign units/leaders persistence.

=== happygrue/Wintermute ===

Has been involved with multiplayer balance and testing for a number of years. Currently working on balancing the default+khalifate era, but interested in, and often available for, testing various aspects game play or mechanics. A good person to bug about getting feedback from the multiplayer community about any relevant issue.

=== loonycyborg ===
Maintainer of Wesnoth's SCons build system and windows packager. Might also help out with other buildsystems.

=== mattsc ===

Has no computer science background and doesn't really know much about how coding should be done, but has been fiddling with Wesnoth AI behavior for a while now, accumulating some empirical experience along the way. He might be able to help with questions on AI behavior and, to a lesser extent, on AI functionality.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Mordante is currently busy rewriting the old gui engine, he will be our expert there as well as already being our area expert for the terrain engine. He also has limited experience with boost asio.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area.

=== shadowm ===
He has been around since late 2007, and has worked in many areas of the game, including WML event commands handling, image path functions, and the add-ons client code. As an add-on content developer, he also knows a lot about the WML language itself (preprocessor, syntax) and the functionality available in single-player campaigns.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== vultraz ===
He can assist with questions related to the Lua GUI2 bindings and their usage.

=== zookeeper ===
Has been around for a long time and has at least a passing familiarity with most things outside the engine code, music and Lua. Maintains a large part of the mainline campaigns and knows the WML language well. Can be contacted when it comes to anything related to WML, gameplay and scenario design, or the mainline content in general.

== Inactive people ==

These people are currently not actively participating in development and are likely not available to help. You can always try, of course. They may also not be entirely up-to-date regarding their areas of expertise anymore.

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Dragonking ===

He is one of our best Wesnoth players, and understands the various strategies well. He has also programmed much of the Wesnoth Formula AI system and understands it well.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== Gabriel Morin (gabba) ===

gabba joined the team in 2010 where he participated in GSoC, and is the conceptor and maintainer of Wesnoth's planning system, codenamed "Whiteboard".

=== ilor ===
2008 GSoC student, worked on and maintains the new map editor in Wesnoth 1.5/1.6/1.7. Has some fairly recent experience with getting "in" the Wesnoth codebase.

=== Karol Nowak (grzywacz) ===
Two years he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on Wesnoth for embedded devices as he worked on the gp2x support.

=== Sapient ===
This developer started working on the GUI and widgets, but recently he focused more on improving the internal mechanics of the WML engine such as variable look-ups and filtering. Sapient is not as active anymore but he does come one IRC in the evenings (U.S.A.). He has touched-up many areas of the code in small ways over time, thus he has a good general knowledge of the C++ code and also has worked a little on some python maintenance scripts.

=== YogiHH ===
Since he is the developer who know most about building under Windows, he will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.
YogiHH also knows quite a bit about the game engine and everything that has to do with replays and savegames.

=== Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

AnimationWML

2014-02-08T01:48:11Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Or more formally:
Each set of square brackets must contain a list, either defined by a range (e.g. [1~4] becomes a list of four, with increments of one, and this works in reverse also from 4~1) or a comma-separated list which can contain any strings (e.g. [1,a,2]). All bracketed lists in the same progressive string must have the same length (after ranges are expanded), and the result is a series of that many images.
A bracketed range where the first element has leading zeroes will be padded to that length throughout. If so, the number specifying the end of the range must have the same number of digits. An asterisk will make n copies of what precedes it in an expansion for [string*N] (which is equivalent to [string,...,string] N times.

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:30:49Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Or more formally:
Each set of square brackets must contain a list, either defined by a range (e.g. [1~4] becomes a list of four, with increments of one, and this works in reverse also from 4~1) or a comma-separated list which can contain any strings (e.g. [1,a,2]). All bracketed lists in the same progressive string must have the same length (after ranges are expanded), and the result is a series of that many images.
A bracketed range where the first element has leading zeroes will be padded to that length throughout. If so, the number specifying the end of the range must have the same number of digits. An asterisk will make n copies of what precedes it in an expansion for [string*N] (which is equivalent to [string1,...stringN].

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:29:22Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Or more formally:
Each set of square brackets must contain a list, either defined by a range (e.g. [1~4] becomes a list of four, with increments of one, and this works in reverse also from 4~1) or a comma-separated list which can contain any strings (e.g. [1,a,2]). All bracketed lists in the same progressive string must have the same length (after ranges are expanded), and the result is a series of that many images.
A bracketed range where the first element has leading zeroes will be padded to that length throughout. If so, the number specifying the end of the range must have the same number of digits. An asterisk will make n copies of what precedes it in an expansion for [string*n].

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:26:37Z

Coffee: Formal description of square bracket syntax

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Or more formally:
Each set of square brackets must contain a list, either defined by a range (e.g. [1~4] becomes a list of four, with increments of one, and this works in reverse also from 4~1) or a comma-separated list which can contain any strings (e.g. [1,a,2]). All bracketed lists in the same progressive string must have the same length (after ranges are expanded), and the result is a series of that many images.
A bracketed range where the first element has leading zeroes will be padded to that length throughout. If so, the number specifying the end of the range must have the same number of digits.

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:19:08Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:16:49Z

Coffee: /* The content of a frame */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout the expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:16:13Z

Coffee: Extra examples and note about leading zero expansions

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout the expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:03:00Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2014-02-08T01:02:39Z

Coffee: Add extra example for square bracket syntax

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-11-09T16:45:53Z

Coffee: Update for 'if' 'else' new capabilities in 1.11.7

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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, and from 1.11.7+ you can 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):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-10-12T23:04:36Z

Coffee: /* Example Syntax */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-10-12T23:03:11Z

Coffee: Note about timing

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25 slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-10-12T23:00:10Z

Coffee: /* Example Syntax */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-10-12T22:59:32Z

Coffee: Update example to be more realistic

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]

'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' 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='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" 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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' 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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-04-01T03:05:17Z

Coffee: remove dev 1.9, as now is standard

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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]
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
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, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<progressive int>
directional_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_color=<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_directional_x=<progressive int>
xxx_directional_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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-04-01T03:03:35Z

Coffee: updated for 1.11.2 syntax enhancements

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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]
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
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, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive 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>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-03-26T20:39:21Z

Coffee: example usage of SOUND:HIT_AND_MISS macro

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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]
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== 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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-03-26T20:28:42Z

Coffee: sound duration not needed any more for sound only frames

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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]
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-16T21:58:05Z

Coffee: make use of new image syntax in example

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-16T21:55:04Z

Coffee: update depreciated syntax (begin/end)

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png
halo=halo[1~4].png:[10,20*3] is equivalent to halo1.png:10,halo2.png:20,halo3.png:20,halo4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-16T21:52:00Z

Coffee: update image to list

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png
halo=halo[1~4].png:[10,20*3] is equivalent to halo1.png:10,halo2.png:20,halo3.png:20,halo4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''image''': the image, or sequence of images, to display during the frame.
** '''image_diagonal''': the image, or sequence of images, 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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-16T21:50:45Z

Coffee: add image to example list

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png
halo=halo[1~4].png:[10,20*3] is equivalent to halo1.png:10,halo2.png:20,halo3.png:20,halo4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-16T21:48:49Z

Coffee: image/image_mod to progressive_string

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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=<progressive string>
image_diagonal=<progressive 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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png
halo=halo[1~4].png:[10,20*3] is equivalent to halo1.png:10,halo2.png:20,halo3.png:20,halo4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2013-02-11T06:46:11Z

Coffee: asterisk syntax for square brackets

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
halo=halo[1~3]:[100,200,300]

for convenience, the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png
halo=halo[1~4].png:[10,20*3] is equivalent to halo1.png:10,halo2.png:20,halo3.png:20,halo4.png:20

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

TerrainGraphicsWML

2013-02-04T09:26:38Z

Coffee: Square bracket expansion allowed in 'flag' parameters

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

InterfaceActionsWML

2013-02-02T07:50:21Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently (requires Wesnoth 1.11.2+):
''halo=scenery/fire[1~8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

TerrainGraphicsWML

2013-02-02T07:49:15Z

Coffee: /* Examples */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

AnimationWML

2013-02-02T07:48:21Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
halo=halo[1~3]:[100,200,300]

the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1~2]-ex[4~5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

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

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

==== post_movement ====
This animation is used after any unit movement

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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

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

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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

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

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

InterfaceActionsWML

2013-01-27T09:08:35Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or suqare bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently:
''halo=scenery/fire[1-8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

InterfaceActionsWML

2013-01-27T09:08:14Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or suqare bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100
or equivalently:
halo=scenery/fire[1-8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

InterfaceActionsWML

2013-01-27T09:07:21Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or suqare bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
or equivalently:
''halo=scenery/fire[1-8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

InterfaceActionsWML

2013-01-27T09:06:46Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.
''Example (where the integer after the colon is the duration of each frame or suqare bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100
or equivalently:
halo=scenery/fire[1-8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

InterfaceActionsWML

2013-01-27T09:06:08Z

Coffee: /* [item] */

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

Part of [[ActionWML]], interface actions are actions that do not have a direct 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.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

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

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

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

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message. Append ~RIGHT() if you want the image to appear on the right side.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''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]''': No '''[option]''' elements have to be used. 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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
** '''[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_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki>You are victorious!</nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* 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.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].
* '''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.
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.
* '''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.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only.
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.
** '''description''': the text of the note.
** {{DevFeature1.11}} '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.

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

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''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 [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) 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.
** '''delayed_variable_substitution ''' {{DevFeature1.11}} (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.

== [clear_menu_item] ==
{{DevFeature1.11}}

Removes a menu item from the scenario.
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.

== 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. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame or suqare bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100 or equivalently halo=scenery/fire[1-8].png:100''
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''redraw''': {{DevFeature1.11}}(boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.

=== [remove_item] ===
Removes any graphical items on a given hex.
* [[StandardLocationFilter]]: the hexes to remove items off
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)

=== [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
* '''gender''': the gender of the fake unit. Example: gender=female
* '''variation''': the variation of the fake unit. Example: variation=undead
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.
=== [move_units_fake] ===
moves multiple images of units along paths on the map. These units are moved in lockstep.
* '''[fake_unit]''': A fake unit to move
** '''type''': the type of 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
** '''skip_steps''': the number of steps to skip before this unit starts moving
=== [hide_unit] ===
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.
* [[StandardUnitFilter]]: All matching units will be hidden

=== [unhide_unit] ===
Stops the currently hidden units from being hidden.
* [[StandardUnitFilter]]: Only the matching units will be unhidden

=== [lock_view] ===
{{DevFeature1.11}} Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.

This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

=== [unlock_view] ===
{{DevFeature1.11}} Unlocks gamemap view scrolling for human players.

=== [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
* {{DevFeature1.11}} [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.
* '''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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').

=== [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.
* {{DevFeature1.11}} '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''false'').
=== [select_unit] ===
Selects a given unit.
* [[StandardUnitFilter]]: The first unit found will be selected.
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').

=== [sound]===
Plays a sound
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
* '''repeat''': repeats the sound for a specified additional number of times (default=0)
=== [sound_source] ===
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
* '''id''': a unique identification key of the sound source
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
* '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
* '''check_shrouded''': possible values "true" and "false" - if true the source will not play if its locations are shrouded
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are 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
===[volume]===
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
* '''music''': Changes the music volume.
* '''sound''': Changes the sound volume.
=== [color_adjust]===
Tints the color of the screen.
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
=== [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).
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. 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).
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.

=== [unit_overlay] ===
Sets an image that will be drawn over a particular unit, and follow it around
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])
* '''image''': the image to place on the unit

=== [remove_unit_overlay] ===
removes a particular overlayed image from a unit
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])
* '''image''': the image to remove from the unit

=== [animate_unit] ===
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)
* '''text''': a text to hover during the animation
* '''red''': red value for the text color (0-255)
* '''green''': green value for the text color
* '''blue''': blue value for the text color
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
* '''[animate]''': a sub block with the same syntax as '''[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.
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.
=== [floating_text]===
Floats text (similar to the damage and healing numbers) on the given locations.
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
* '''text''': the text to display.

The default text color is '''#6b8cff'''. To change the color, use [[#Formatting|Pango markup]]. For example:

<pre>
# Float some golden yellow text at 20,20.
[floating_text]
x,y=20,20
text="" + _ "Your text here" + ""
[/floating_text]
</pre>

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

Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).

=== [open_help] ===
Opens the in-game help.
* '''topic''': the id of the topic to open
=== [show_objectives] ===
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
* '''side''': the side to show the objectives. If not set, all sides are used.
* '''[[StandardSideFilter]]''' {{DevFeature1.11}} tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.

=== [chat] ===
Displays a message in the chat area.
* '''speaker''': (default="WML") A string for the name of the sender of the message.
* '''message''': The message that should be displayed.
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.

== 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].
* '''{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>. For example, '''{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]]

TerrainGraphicsWML

2013-01-27T09:04:17Z

Coffee: /* The toplevel [terrain_graphics] tag */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01-08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2013-01-27T09:00:19Z

Coffee: /* Examples */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches. A square bracket expansion, as in animationWML for halos may be used.
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01-08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2013-01-27T08:59:21Z

Coffee: /* Examples */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches. A square bracket expansion, as in animationWML for halos may be used.
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):
[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01-08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2013-01-27T08:59:02Z

Coffee: /* Examples */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches. A square bracket expansion, as in animationWML for halos may be used.
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an interframe transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):
[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01-08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2013-01-27T08:54:54Z

Coffee: /* The toplevel [terrain_graphics] tag */

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches. A square bracket expansion, as in animationWML for halos may be used.
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

AnimationWML

2013-01-27T08:51:19Z

Coffee: /* Progressive parameters */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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 an expanded syntax:

halo=halo1.png:100,halo2.png:200,halo3.png:300

or equivalently,
halo=halo[1-3]:[100,200,300]

the square bracket expansion works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07-10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
halo=halo[5-3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
halo=halo[1-2]-ex[4-5].png:[100,200] is equivalent to halo=halo1-ex4.png:100,halo2-ex5:200.png

==== 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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

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

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

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

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

no default animation is needed

note that is not triggered for WML triggered animations

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

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

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

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== 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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2013-01-27T07:27:00Z

Coffee: /* Field Description */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelout ====
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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

==== levelin ====
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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== 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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2013-01-27T07:14:50Z

Coffee: /* Field Description */

{{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 its 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]
[filter_attack]
name=bow
[/filter_attack]
'''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>
directional_x=<dev feature 1.9,progressive int>
directional_y=<dev feature 1.9,progressive int>
layer=<progressive int>
auto_hflip=<dev feature 1.9, boolean>
auto_vflip=<dev feature 1.9, boolean>
primary=<dev feature 1.9, boolean>
[/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='''. If specified by timing in a progressive string, such as a halo, this will be automatically calculated.
** '''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
** '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
** '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
** '''layer''': layer used to draw the frame, see discussion bellow
** '''auto_hflip''': should the image flip horizontally depending on sprite orientation
** '''auto_vflip''': should the image flip vertically depending on sprite orientation
** '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== 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_color=<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>
directional_x=<dev1.9,progressive int>
directional_y=<dev1.9,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_color=<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_directional_x=<dev1.9,progressive int>
xxx_directional_y=<dev1.9,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 description 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 following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy 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 enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. 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 matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation 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
* '''value_second''': 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#Filtering Terrains|Filtering Terrains]]. this has been replaced by '''terrain_type'''
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|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 [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria 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#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. 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). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering 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

''value_second='' 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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelout ====
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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

==== levelin ====
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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0: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='' contains the number of steps already taken

''value_second='' contains the number of steps left

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_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== 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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is not used, and always contains 0

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

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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 damage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

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

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=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

''value_second='' 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

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

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

''value_second='' 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

''value_second='' 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. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

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
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[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
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[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"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=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

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Formula AI Code Library

2011-12-04T07:53:05Z

Coffee:

This page lists Formula AI code examples that can be used directly in a scenario or as templates for further development. If you have problems with any of them or would like to see additional examples let us know in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 this forum thread]. If you have examples to add, you can also let us know there and we will post them, or feel free to edit these wiki pages yourself.

* Check out [[Formula AI Howto]] for a practical guide for setting up and testing these examples in a scenario.
* Additional examples can be found in the Wesnoth data directory under ai/formula/. See [[EditingWesnoth]] for locating the data directory.
* Lua AI code examples can be found in the [[Lua AI Code Library]].

==Swamp Lurker Moves==

This is the Formula AI adaptation of the WML swamp lurker code from [http://forums.wesnoth.org/viewtopic.php?f=8&t=34970 Grnk the Mighty]. Swamp lurkers have the 'swamp_submerge' ability, meaning they are invisible in swamps unless an enemy unit is adjacent to them. They are dumb, impulse-drive creatures which move as follows:

* They can move across most terrain, but only stop on swamp.
* All lurkers move individually, there is no strategy.
* If there are enemies within reach (next to swamp terrain), a lurker will attack the unit with the fewest hitpoints.
* If no unit is in reach, the lurker will move to a random reachable swamp hex.

In Grnk, this behavior is coded in WML (the WML code can be found in '1_unit_macros.cfg' in the Grnk folder or in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976#p506852 this forum post]). The adaptation to Formula AI follows below. A [[Lua_AI_Code_Library#Swamp_Lurker_Moves|Lua AI version]] exists as well.

<div style="height: 250px; overflow:auto">
fai 'lurker_moves.fai'
# run_file('~add-ons/AItest/ai/lurker_moves.fai') #

def is_swamp(map, xx, yy)
# Tests whether terrain at xx,yy is swamp_water #
map(
filter( map.terrain, (x=xx) and (y=yy)),
self.id
)[0] = 'swamp_water';

def reachable_swamp(unit_loc,map)
# get all reachable swamp locs for unit at unit_loc #
# exclude own location #
filter(
unit_moves( unit_loc ),
(is_swamp( map, x, y )) and (self != unit_loc)
);

def random(array)
# Picks a random elements of 'array' #
array[(1d size(array) - 1)];

def reachable_enemies_next_to_swamp(unit_loc,attacks,map)
# Returns all the attacks for enemies that the unit at 'unit_loc' #
# can reach and that are next to a swamp hex #
filter(
map( attacks.attacks, self),
(move_from = unit_loc) and (is_swamp( map, attack_from.x, attack_from.y))
);

def weakest_defender(attacks)
# Get the enemy with the lowest HP #
choose( attacks, -unit_at(defender).hitpoints
);

# Attack if possible, otherwise random move #
if( size(possible_attacks) != 0,
weakest_defender(possible_attacks),
if( size(swamp_in_reach) != 0,
move(me.loc,random(swamp_in_reach)),
end)
)

where possible_attacks = reachable_enemies_next_to_swamp( me.loc, my_attacks, map)

where swamp_in_reach = reachable_swamp(me.loc, map)

faiend
</div>

This code is meant to be in a file 'lurker_moves.fai. It can be used with the [[Formula_AI_Howto#Setting_up_the_Formula_AI_unit_formulas_Stage|Formula AI ''unit_moves'' stage]] by including

[ai]
formula={lurker_moves.fai}
[/ai]

in the definition of all swamp lurker units. Or it can be set up as a [[Formula_AI_Howto#Setting_up_the_RCA_main_loop_Stage_and_Candidate_Actions|candidate action]] that applies to all swamp lurker units of a given side:

[candidate_action]
engine=fai
name=lurker_moves
type=movement
[filter]
me="filter(input, (input.type = 'Swamp Lurker'))"
[/filter]
evaluation=300000
action={lurker_moves.fai}
[/candidate_action]

Notes:
* This code can, of course, also be used with any non-lurker unit as long as it is able to move through swamp.
* This example currently only works with "pure" swamp, not with quagmire tiles, but the extension to include those should be obvious.

==Specifying simple AI combat targets==
This side wide Formula AI example is also taken from [http://forums.wesnoth.org/viewtopic.php?f=8&t=33664 The Great Quest] by Coffee.

When the AI has a chance/choice of units to kill, sometimes you might want it to try to kill a certain unit or type of unit in preference of another. The following example makes the AI try to kill a ''loyal'' unit in preference of other units where the chance of a kill from one attack is greater than 50% (it then further prioritizes by chance to kill ''loyal'' units):

*Notes: There is a specific exclusion for the AI leader, so it doesn't get goaded into a bad position. There is also a calculation done to attack from the best terrain spot available for each possible attack pair. Calculate_outcome gives a result in the range of 0 to 10000, with >=5000 meaning a 50% chance of success.

[side]
side={SIDE}
controller=ai
#other params here
[ai]
#others here such as ''grouping'' or ''aggression''
{MODIFY_AI_ADD_CANDIDATE_ACTION {SIDE} main_loop (
[candidate_action]
id=go_for_loyal_units
name=go_for_loyal_units
engine=fai
type=attack
[filter]
me="filter(input, 'me', me.leader=0)"
target="filter(input, 'target', index_of('loyal',target.traits) != -1)"
[/filter]
evaluation="if(max_possible_damage(me,target)>=target.hitpoints, if(ca_prob>=5000, {AI_CA_COMBAT_SCORE}+ca_prob,0), 0)
where ca_prob=calculate_outcome(me.loc, choose(filter(map(filter(my_moves.moves, src=me.loc), dst), distance_between(self, target.loc) = 1), defense_on(me, self)), target.loc)[1].probability[0]"
action="attack(me.loc, choose(filter(map(filter(my_moves.moves, src=me.loc), dst), distance_between(self, target.loc) = 1), defense_on(me, self)), target.loc, -1)"
[/candidate_action]
)}
[/ai]
[/side]

==Recruiting certain types of units on particular hexes==
This Formula AI example is from a multiplayer campaign, [http://forums.wesnoth.org/viewtopic.php?f=8&t=33664 The Great Quest], by Coffee.

As it currently stands in Wesnoth 1.9, the AI recruits units based on a ''recruitment_pattern'' AI parameter. This sometimes can lead to non-optimal scout recruiting, etc. The following code attempts to remedy this by suggesting that certain units be recruited on certain hexes to improve village grabbing, etc. (but could also be used to recruit a wider variety of units within each ''recruitment_pattern'' parameter).

This code specifies to recruit an appropriate ''scout'' unit (from default faction units) to grab a village 8 tiles away on (7, 24) by flat for side 4. *Note: undead scouts are excluded as ghost only moves 7 hexes and saurians as they move only 6, with quick scout moving 7.

[event]
name=turn 1

#recruit 8 movement scout unit to get village(7,24) fast
{MODIFY_AI_ADD_CANDIDATE_ACTION 4 main_loop (
[candidate_action]
id=recruit_scout
name=recruit_scout
engine=fai
type=movement
evaluation="if(turn=1 and unit_at(loc(7,24))=null(), {AI_CA_RECRUITMENT_SCORE}+400, 0)"
action="recruit(scout_units[(1 d size(scout_units))-1],loc(7,24))
where scout_units=map(filter(my_recruits,usage='scout' and undead=0 and id!='Saurian Skirmisher'),id)"
[/candidate_action]
)}
[/event]

#delete at turn 2, as we should have the wanted scout recruited by then
[event]
name=turn 2

{MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION 4 main_loop recruit_scout}
[/event]

The evaluation is for turn 1 because this is when we want to recruit this particular unit here. It also checks to see if there is already a unit on this hex as the candidate actions are run more than once. With a score of {AI_CA_RECRUITMENT_SCORE}+400, this formula will be evaluated just before the regular recruitment stage and simply adds to it.

=== Specifying scouts not attack whilst scouting ===

In addition to specifying that scouts should be recruited on certain hexes, an ''aspect'' can be set so that the AI does not choose to attack whilst it could be scouting instead. An example code for this is:

[side]
side={SIDE}
[ai]
{MODIFY_AI_ADD_ASPECT {SIDE} attacks (
[facet]
name=testing_ai_default::aspect_attacks
id=hold_off_initial_scout_attack
invalidate_on_gamestate_change=yes
[filter_own]
[not]
type="Cavalryman,Drake Glider,Elvish Scout,Footpad,Ghost,Gryphon Rider,Vampire Bat,Wolf Rider"
[/not]
[/filter_own]
[/facet]
)}
[/ai]
[/side]
[event]
name=turn 3
{MODIFY_AI_TRY_DELETE_ASPECT {SIDE} attacks hold_off_initial_scout_attack}
[/event]

The above code stops the calculation of combat for the units matching the ''filter_own'' ''Single Unit Filter'' expression. The turn 3 event deletes this changed behavior (presumably after the scouts have collected a village).

This approach might also be useful for when it is desired that a certain unit or type of unit should not attack. Alternatively, it could be useful to specify that a beserker, say, should not attack unless a formula AI candidate action expression evaluates to > 0 (be careful that you don't rely on the built-in calculation functions though, as they are not executed with this aspect set).