Custom Animation Functions

Custom Animation Functions

Custom animation functions are an advanced feature that is only intended for users who know Lua. As such, the following page will assume you are familiar with Lua and related programming concepts. For more information on Lua, see Programming In Lua.

---

WeakAuras allows the user to define custom "paths" for all animation types. For Translation animations, the term "path" is literal; the custom path actually defines what x and y coordinates the display will take. For other animation types, the term "path" simply refers to the manner in which the display's original value is combined with the value specified by the animation to determine a final value, for whatever aspect of the display the animation is meant to alter.

WeakAuras' animation system is based on 5 distinct types of animation: Alpha, Translation, Scale, Rotate, and Color. Every display type supports Alpha, Translation and Color animations. Some display types do not support Scale animations (mostly because it is not possible to cleanly apply Scale animations to text). Only Textures support Rotate animations.

To define a custom animation function in WeakAuras, you must first change the animation's Type to "Custom Function". This will provide a multi-line editbox in which the Custom Function can be written. The custom function should be an anonymous function. It will be called every frame during the animation to determine what value should be applied to the display. The arguments passed to the function, and values which should be returned by the function, vary by animation type.

---

Alpha

Alpha animations denote a change in transparency.

Alpha animations provide 3 arguments:

• arg1 - progress: A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
• arg2 - start: The Alpha value that is defined as "normal" for the display, expressed as a value between 0 (invisible) and 1 (completely opaque). This would be set in the Display tab.
• arg3 - delta: The difference between the "normal" alpha of the display and the alpha value specified for the animation (using the slider right below the Custom Function box). For example, if a display is set to 100% alpha normally, and its Alpha animation is set to 33%, then "delta" would be -0.66.

An Alpha animation function should return a single value:

• return1 - alpha: The alpha value that the display should have at the current point in the animation.

The "Normal" Alpha animation path, which simply transitions from one Alpha value to another in a linear fashion, looks like this:

function(progress, start, delta)
  return start + (progress * delta)
end

---

Translate

Translate animations denote a change in position. Note that a display's x and y coordinates are defined in terms of the distance between its reference anchor point and its self anchor point, both of which can be set in the Display tab. In WoW, x coordinates go from 0 at the left side of the screen to a positive value at the right side of the screen, and y coordinates go from 0 at the bottom of the screen to a positive value at the top of the screen. This is vertically inverse compared to many coordinate systems used in programming.

Translate animations provide 5 arguments:

• arg1 - progress: A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
• arg2 - startX: The x coordinate that is defined as "normal" for the display (specifically, the x coordinate of its anchor point), expressed in pixels. This would be set in the Display tab.
• arg3 - startY: The y coordinate that is defined as "normal" for the display (specifically, the y coordinate of its anchor point), expressed in pixels. This would be set in the Display tab.
• arg4 - deltaX: The value specified by the animation using the "X Offset" slider underneath the Custom Function box.
• arg5 - deltaY: The value specified by the animation using the "Y Offset" slider underneath the Custom Function box.

A Translate animation function should return two values:

• return1 - x: The resulting x coordinate of the display.
• return2 - y: The resulting y coordinate of the display.

The "Normal" Translate animation path, which simply transitions from one position to another in a straight line, looks like this:

function(progress, startX, startY, deltaX, deltaY)
  return startX + (progress * deltaX), startY + (progress * deltaY)
end

---

Scale

Scale animations denote a change in size. A display's scale in either the x or y direction is defined in relation to its normal size. This means that a display that is normally 200x200 pixels, if under a Scale animation whose current values are 1.5 and 0.8, will be 300x160 pixels.

Scale animations provide 5 arguments:

• arg1 - progress: A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
• arg2 - startX: The "normal" scale of the display in the x direction. This is always 1.
• arg3 - startY: The "normal" scale of the display in the y direction. This is always 1.
• arg4 - scaleX: The value specified by the animation using the "X Scale" slider underneath the Custom Function box.
• arg5 - scaleY: The value specified by the animation using the "Y Scale" slider underneath the Custom Function box.

A Scale animation function should return two values:

• return1 - scaleX: The resulting scale of the display in the x direction.
• return2 - y: The resulting scale of the display in the y direction.

The "Normal" Scale animation path, which simply scales from one size to another in a linear fashion, looks like this:

function(progress, startX, startY, scaleX, scaleY)
  return startX + (progress * (scaleX - startX)),
          startY + (progress * (scaleY - startY))
end

Note that the scaleX and scaleY values passed to the Scale function are interpreted as being absolute values which denote the eventual maximum scale of the animation, not the difference between the original scale (which is always 1x1) and the end scale. This is a different behavior than the rest of the animation types.

Also note that Scale animations will differ slightly based on the display's anchor point, which will not change positions. A display anchored by its center will scale from the center, whereas a display anchored by a corner will scale from that corner.

---

Rotate

Rotate animations denote a change in rotation. Texture displays are the only display type that is able to rotate (and only if Allow Full Rotation is enabled).

Rotate animations provide 3 arguments:

• arg1 - progress: A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
• arg2 - start: The Rotation value that is defined as "normal" for the display, expressed in degrees. This would be set in the Display tab.
• arg3 - delta: The rotation value specified for the animation, using the slider right below the Custom Function box.

A Rotate animation function should return a single value:

• return1 - rotation: The rotation value that the display should have at the current point in the animation.

The "Normal" Rotate animation path, which simply transitions from one Rotation value to another in a linear fashion, looks like this:

function(progress, start, delta)
  return start + (progress * delta)
end

Color

Color animations denote a change in color.

Color animations provide 9 arguments:

• arg1 - progress: A value between 0 and 1 which represents how far along the animation is. Main and Finish animations start at 0 and end at 1, while Start animations start at 1 and end at 0.
• arg2, arg3, arg4, arg5 - r1 g1 b1 a1: The Color value that is defined as "normal" for the display. This would be set in the Display tab.
• arg6, arg7, arg8, arg9 - r2 g2 b2 a2: The color value specified for the animation, using the color selector below the Custom Function box.

A Color animation function should return a 4 values:

• return1, return2, return3, return4 - r g b a: The color values that the display should have at the current point in the animation.

The "Color" animation path, which simply transitions from one Color value to another in a linear fashion, looks like this:

function(progress, r1, g1, b1, a1, r2, g2, b2, a2)
      return r1 + (progress * (r2 - r1)), g1 + (progress * (g2 - g1)), b1 + (progress * (b2 - b1)), a1 + (progress * (a2 - a1))
    end