AnimationWML

Animation and sound

Several key/tags of the [unit] and [attack] tags do not affect gameplay, but are available to control the way units and their attacks will be animated and heard.

All times (see begin, end, time) are measured in milliseconds, or 1000ths of seconds. Unit movement is automatically animated based on these times; the attacking unit or missile begins in the center of the hex at the lowest begin time, then slides continuously to the center of the defender's hex, which it reaches at time=0. If the attack is a melee attack, the unit will then slide continuously back onto its own hex until the highest end time. Note that in accelerated mode or under a lot of stress the game engine can skip some frames (sounds included), and very short frames (less than 10ms?) may get skipped even in normal circumstances.

All unit animations use the same engine, so most tags and keys are common for all animations types.

[animation] blocks

All animations are enclosed in [animation] tags. The actual name of the tag changes depending on the type of animation (so for example healing animations are written inside [healing_anim] tags, death anims inside [death] tags, and so on).

Individual animation frames are described by [frame] tags.

[animation]: all animations are enclosed in [animation] tags. The actual name of the tag changes depending on the type of animation (so for example healing animations are written inside [healing_anim] tags, death anims inside [death]: tags, and so on), but here we refer to all of them simply as [animation] tags, since they all work the same. Wherever you can put an [animation]: tag, you can put multiple ones - you can use this to create variations on animations or to have some animations be used only in certain circumstances (like only on a certain terrain or only when delivering a killing blow in combat to name a few possibilities).
- [frame]: describes what an animation should display at a given time. Only one frame can be displayed at a time.
  - begin: the time at which this frame should start (in milliseconds).
  - end: the time at which the animation should end.
  - duration: how long the frame should be displayed. Use instead of begin= and end=.
  - image: the image to display during the frame.
  - 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.
  - 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.
- [missile_frame]: can only be used for ranged attacks; describes a frame of animation for the projectile. Most commonly only one [missile_frame] is used and the missile isn't actually animated. Accepts the same keys as [frame] and also the following:
  - image_diagonal: the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
- [XXX_frame]: you can have as many "sub animations" within an animation by defining them in their own type of frame blocks. note that XXX should not start with an underscore ("_") this is reserver for internal use by the engine
  - image_diagonal: the image to display when the animation occurs diagonally (directions ne,se,sw,nw).

Progressive parameters

You can make a value of a key smoothly slide from one starting value to another one during the duration of the [frame]. To make a frame fade from normal to completely transparent, 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

if you want to define this parameter for other sub animation, use the prefix of that animation. For instance, the default sliding of missile animations can be specified with

missile_offset=0~0.8

When defining an animation for use in a specific situation, you have a variety of keys with which you can define when the animation is to be used. The filters go directly inside the [animation] tag. Different types of animations have slightly different set of filters available. See further below for a detailed explanation on how more complex filtering works.

Generic animation filters available for all animations

terrain: a list of comma separated terrain letters, the animation will only be used on these terrains. See FilterWML.
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.
[unit_filter]: this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple [unit_filter] blocks in an animation.
[secondary_unit_filter]: this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple [secondary_unit_filter] blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail
[neighbour_unit_filter]: this will filter using a standard unit filter on allunits in adjacent hexes. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple [neighbour_unit_filter] blocks in an animation. This filter will earn you one point for each matching neighbouring unit, and will fail if no unit matches the criteria (i.e no neighbour or no matching neighbour) .

Progressive parameters can be set both in the [frame] or in the [animation] the general rule is that frame level specification overrides animation level specifications, which overrides engine provided defaults. The following parameters can be specified both at animation and at frame level

alpha
halo
halo_x
halo_y
offset
blend_color
blend_ratio

Note that these can be set as animation-level parameters also for sub-animations (see [XXX_frame] above) by using keys XXX_offset, XXX_alpha, etc.

Fighting animation filters

- 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.
- range: a list of ranges that the attack must match for this animation to be used.
- damage_type: a list of damage types that the animation should be used with (damage type of the attack).
- attack_special: a list of special abilities the attack should have.
- swing: a list of numbers representing the swing numbers this animation should match (numbered from 1).
- damage: a comma separated list of values of the damage the defender will take (note that damage is 0 if the attack misses).
- [attack_filter]: a standard attack filter to match on the attacker's attack. See FilterWML.
- [secondary_attack_filter]: a standard attack filter to match on the defender's attack. See FilterWML. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.

Attack animation: [attack_anim]

This animation is played when a unit attempts a blow on another unit. The attacking unit is always facing the defending unit.

This animation can contain some [missile_frame] blocks, see below...

Defensive animation: [defend]

This animation is used when facing a blow in a fight. The defending unit is always facing the attacking unit.

Death animation: [death]

This animation is used when the unit dies, before it is removed from display. It is called after the fight is finished and the hits criteria is always set to kill.

Movement animation: [movement_anim]

This animation is used when a unit is moving. The moving unit is always facing the hex it's moving into. The animation will be truncated if the unit reaches its destination before the end of the movement. The animation will also be ended if the unit enters a hex where the current animation has a negative score, but not if its still valid (but not the best score).

Standing animation: [standing_anim]

This animation is used when a unit is standing and doing nothing.

Idle animation: [idle_anim]

This animation is called randomly every now and then when the unit is idle.

Leading animation: [leading_anim]

This animation is used when a unit is using it's leadership ability on another unit. The leading unit is always facing the unit it leads.

Healing animation: [healing_anim]

This animation is used when a unit has a healing ability and is using it on another unit. The healing unit is always facing the unit it heals.

damage: a comma separated list of values: the damage healed.

Teleport animation: [teleport_anim]

This animation is used when a unit teleports by using the teleport ability (not when the unit is moved by using the [teleport] tag). The part of the animation before time 0 is displayed at the starting point, and the rest displayed when arriving at the destination.

Victory animation: [victory_anim]

This animation is used when the unit kills another unit, during the other unit's death animation. It is called after the fight is finished and the hits criteria is always set to kill.

Poison animation: [poison_anim]

This animation is used when the unit suffers poison damage (at the beginning of turn).

damage: a comma separated list of values: the damage suffered.

Healed animation: [healed_anim]

This animation is used when the unit is healed (by a healer or a village).

healing: a comma separated list of values: the HP healed.

Recruit animation: [recruit_anim]

This animation is used when a unit is recruited (or created via the plague special ability).

Level-in animation: [levelin_anim]

This animation is used when a unit has leveled. The new unit is displayed, and this animation is played immediately.

Level-out animation: [levelout_anim]

This animation is used when a unit has leveled. The old unit is still displayed, and this animation is played just before changing it to the new unit.

Custom animations: [extra_anim]

This animation defines a custom animation that can be called in WML events (via the [animate_unit] tag), to make a unit display arbitrary animations at arbitrary times.

flag: this identifies the animation, and will be used to choose the correct animation to play.

How animations are chosen

Wherever you can put an animation block, you can put multiple ones. So an interesting question is which one of them will the engine choose when the animation should be displayed? Simply put, the engine always chooses the one that matches the given filtering best. If several match equally well, one of them is picked randomly every time. Below is a more detailed and technical explanation of the choosing process.

The animation engine always uses the same rules to choose an animation. I will take the example from movement animations. Movement animations can take two filters (via special flags in the animation block) to filter on movement direction and on the terrain the unit is currently on. So, the engine takes all movement animations and assigns them scores with the following algorithm:

the animation starts with a score of 0 for each criteria,

if filter is not there, the score is unchanged
if filter is not matched the animation is given a score of -1 and the algorithm ends (disqualified)
if filter is matched, the score is increased by one

After that, the engine takes all top score animations and chooses a random one.

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 animatio 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)

How animations are synchronized

Some events require multiple units playing different animations simultaneously. Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too).

In that case, 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).

When you use duration= to time [frame]s instead of the begin= and end= keys (which is recommended), animation blocks can specify a start_time= key. This is a virtual time at which the animation should be launched. Suppose the attack animation has start_time=-150 and the defense animation has start_time=-100: for 50ms, the attack animation will play alone, then the defense animation will start, they will both reach their virtual 0 at the same time (which is the time of impact) and then continue. If no start_time is available, it is defaulted to zero.

[if] and [else]

If 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 useful. 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]