WeakAuras

Custom Animation Functions

r8

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 4 distinct types of animation: Alpha, Translation, Scale, and Rotate. Every display type supports Alpha and Translation 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 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.

An Alpha 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 Alpha value to another in a linear fashion, looks like this:

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

Facts

Date created
Nov 21, 2010