Animation System - WeakAuras

Overview

WeakAuras provides a powerful animation system that can slide, fade, scale, rotate, and color-shift your displays. Animations run at different stages of a display’s lifecycle.

Animations use Animations.lua for smooth, efficient visual effects coordinated across all displays.

Animation Phases

Start
Main
Finish

{
  start = {
    type = "preset",
    preset = "slidetop",
    duration = 0.3
  }
}

Plays when the display first appears.

{
  main = {
    type = "preset",
    preset = "pulse",
    duration = 2
  }
}

Loops while the display is shown.

{
  finish = {
    type = "preset",
    preset = "slidedown",
    duration = 0.3
  }
}

Plays when the display is about to hide.

Preset Animations

Quick, pre-configured animations:

Movement Presets

{
  preset = "slidetop",      // From top
  preset = "slidebottom",   // From bottom
  preset = "slideleft",     // From left
  preset = "slideright"     // From right
}

Custom Animations

Create complex, multi-effect animations:

{
  type = "custom",
  
  // Slide (translate)
  use_translate = true,
  x = 100,          // Pixels right
  y = 50,           // Pixels up
  
  // Fade (alpha)
  use_alpha = true,
  alpha = 0,        // Target alpha
  
  // Scale (zoom)
  use_scale = true,
  scalex = 1.5,     // 150% width
  scaley = 1.5,     // 150% height
  
  // Rotate
  use_rotate = true,
  rotate = 360,     // Degrees
  
  // Color shift
  use_color = true,
  colorR = 1,
  colorG = 0,
  colorB = 0,
  colorA = 1
}

Animation Types

Slide (Translate)

{
  use_translate = true,
  translateType = "straightTranslate",  // Linear movement
  x = 100,          // Horizontal offset
  y = -50,          // Vertical offset
  duration = 0.5
}

Negative values move left/down, positive values move right/up.

Fade (Alpha)

{
  use_alpha = true,
  alphaType = "straight",  // Linear fade
  alpha = 0,               // Fade to transparent
  duration = 0.3
}

Scale (Zoom)

{
  use_scale = true,
  scaleType = "straightScale",
  scalex = 2.0,  // 200% width
  scaley = 2.0,  // 200% height
  duration = 0.4
}

Scale values less than 1.0 shrink, greater than 1.0 grow.

Rotate

{
  use_rotate = true,
  rotateType = "straight",
  rotate = 360,   // Full rotation
  duration = 2.0
}

Color Shift

{
  use_color = true,
  colorType = "straightColor",
  colorR = 1,  // Red
  colorG = 0,
  colorB = 0,
  colorA = 1,  // Opaque
  duration = 0.5
}

Duration Types

Seconds
Relative

{
  duration_type = "seconds",
  duration = 2.0  // 2 seconds
}

Fixed time duration.

{
  duration_type = "relative",
  duration = 0.5  // 50% of trigger duration
}

Proportional to trigger duration/progress.

Easing Functions

Control animation acceleration:

{
  easeType = "none",           // Linear
  easeType = "easeIn",         // Accelerate
  easeType = "easeOut",        // Decelerate
  easeType = "easeInOut",      // Smooth both ends
  easeStrength = 3             // Easing intensity
}

None

Linear, constant speed

Ease In

Starts slow, accelerates

Ease Out

Starts fast, decelerates

Ease In/Out

Smooth start and end

Animation Properties

Inverse

{
  inverse = true  // Play animation backwards
}

Loop

{
  loop = true  // Repeat animation
}

Only main animations typically use loop. Start/finish animations run once.

Common Animation Patterns

Fade In on Activate

{
  start = {
    type = "custom",
    use_alpha = true,
    alpha = 0,
    duration = 0.3,
    easeType = "easeOut"
  }
}

Slide from Side

{
  start = {
    type = "custom",
    use_translate = true,
    x = -100,  // From left
    y = 0,
    duration = 0.4,
    easeType = "easeOut"
  }
}

Pulsing Glow

{
  main = {
    type = "custom",
    use_alpha = true,
    alpha = 0.5,  // Pulse to 50%
    duration = 1.0,
    easeType = "easeInOut",
    loop = true,
    inverse = true  // Reverse each loop
  }
}

Grow on Proc

{
  start = {
    type = "custom",
    use_scale = true,
    scalex = 0.5,  // Start small
    scaley = 0.5,
    duration = 0.2,
    easeType = "easeOut"
  }
}

Spin Continuously

{
  main = {
    type = "custom",
    use_rotate = true,
    rotate = 360,
    duration = 3.0,
    loop = true
  }
}

Flash Red

{
  start = {
    type = "custom",
    use_color = true,
    colorR = 1,
    colorG = 0,
    colorB = 0,
    colorA = 1,
    duration = 0.2,
    easeType = "easeInOut"
  }
}

Bounce In

{
  start = {
    type = "custom",
    use_translate = true,
    y = 100,  // Drop from above
    duration = 0.5,
    easeType = "easeOut",
    easeStrength = 5  // Strong bounce
  }
}

Advanced Techniques

Sequential Animations

// Use finish callback (custom code)
aura_env.animationFinished = function()
  // Trigger next animation or action
end

Custom Animation Functions

{
  translateType = "custom",
  translateFunc = [[
    function(progress, startX, startY, deltaX, deltaY)
      // Custom motion path
      local x = startX + deltaX * progress
      local y = startY + deltaY * math.sin(progress * math.pi)
      return x, y
    end
  ]]
}

Coordinated Group Animations

Animations in groups can be synchronized:

// Internal: Animations share progress if same duration
if duration == animations[childKey].duration then
  progress = animations[childKey].progress
end

Animation State

Active animations are tracked:

animations[key] = {
  progress = 0.5,           // 0-1 completion
  duration = 2.0,
  startX = 0,
  startY = 0,
  startAlpha = 1.0,
  // ...
  region = region,
  type = "main",
  loop = true
}

Performance

Animation Updates

Animations update on frame tick (OnUpdate). Many simultaneous animations may impact FPS.

Complex Easing

Custom easing functions are calculated each frame. Keep them simple.

Group Coordination

Groups attempt to sync child animations, which adds overhead.

Canceling Animations

// Internal API
Private.CancelAnimation(region, resetPos, resetAlpha, resetScale, resetRotation, resetColor, doOnFinished)

Animations auto-cancel when:

Display hides
New animation starts on same property
Trigger state changes

Troubleshooting

Animation Not Playing

Verify animation is enabled
Check duration > 0
Ensure display is visible
Verify animation phase (start/main/finish)

Animation Jerky

Reduce easeStrength
Use simpler easing type
Check for FPS issues
Avoid very short durations

Wrong Direction

Toggle inverse setting
Check sign of x/y/rotate values
Verify scale > 1.0 for grow, < 1.0 for shrink

Animation Doesn't Reset

Ensure animation isn’t looping indefinitely
Check if finish animation is canceling start
Verify resetPos/resetAlpha are working

Best Practices

Animation Presets Reference

Preset	Description	Properties
`slidetop`	Slide from top	translate y: -100
`slidebottom`	Slide from bottom	translate y: 100
`slideleft`	Slide from left	translate x: -100
`slideright`	Slide from right	translate x: 100
`grow`	Grow from center	scale: 0 → 1
`shrink`	Shrink to center	scale: 1 → 0
`fade`	Fade in/out	alpha: 0 → 1
`pulse`	Pulsing scale	scale: 1 → 1.2 → 1 (loop)
`bounce`	Bounce effect	translate + easing

Display Types

What can be animated

Conditions

Trigger animations conditionally

Custom Code

Advanced animation control

Architecture

Triggers

Display Types

Customization

​Overview

​Animation Phases

​Preset Animations

​Movement Presets

​Custom Animations

​Animation Types

​Slide (Translate)

​Fade (Alpha)

​Scale (Zoom)

​Rotate

​Color Shift

​Duration Types

​Easing Functions

None

Ease In

Ease Out

Ease In/Out

​Animation Properties

​Inverse

​Loop

​Common Animation Patterns

​Fade In on Activate

​Slide from Side

​Pulsing Glow

​Grow on Proc

​Spin Continuously

​Flash Red

​Bounce In

​Advanced Techniques

​Sequential Animations

​Custom Animation Functions

​Coordinated Group Animations

​Animation State

​Performance

​Canceling Animations

​Troubleshooting

​Best Practices

​Animation Presets Reference

​Related Topics

Display Types

Conditions

Custom Code

Build docs developers (and LLMs) love

Overview

Animation Phases

Preset Animations

Movement Presets

Custom Animations

Animation Types

Slide (Translate)

Fade (Alpha)

Scale (Zoom)

Rotate

Color Shift

Duration Types

Easing Functions

Animation Properties

Inverse

Loop

Common Animation Patterns

Fade In on Activate

Slide from Side

Pulsing Glow

Grow on Proc

Spin Continuously

Flash Red

Bounce In

Advanced Techniques

Sequential Animations

Custom Animation Functions

Coordinated Group Animations

Animation State

Performance

Canceling Animations

Troubleshooting

Best Practices

Animation Presets Reference

Related Topics