Animations - BetterHud

BetterHud provides a powerful equation-based animation system that allows you to create smooth, dynamic movements for your HUD elements.

Animation Basics

Animations in BetterHud are defined using mathematical equations that control position over time:

my_layout:
  images:
    1:
      name: my_image
      x: 0
      y: 0
  animations:
    duration: 60 # Animation length in ticks (3 seconds)
    x-equation: 0 # X position stays at 0
    y-equation: 3cos(t/30 * pi) # Y oscillates

Animation Properties

Duration

The total length of the animation cycle in ticks (20 ticks = 1 second):

animations:
  duration: 20 # 1 second
  duration: 40 # 2 seconds
  duration: 60 # 3 seconds

Equations

Position equations use the variable t (current tick in the animation):

x-equation: Horizontal offset from base position
y-equation: Vertical offset from base position

animations:
  duration: 60
  x-equation: t # Moves right over time
  y-equation: -t # Moves up over time

Mathematical Functions

BetterHud supports various mathematical functions through the exp4j library:

Trigonometric Functions

# Sine wave (smooth up and down)
y-equation: 10sin(t/10)

# Cosine wave (smooth side to side)
x-equation: 10cos(t/10)

# Tangent wave
y-equation: tan(t/20)

Basic Operations

# Addition
x-equation: t + 5

# Subtraction  
y-equation: 10 - t

# Multiplication
x-equation: t * 2

# Division
y-equation: t / 3

# Exponentiation
x-equation: t^2

Mathematical Constants

# Pi (π)
y-equation: sin(t/30 * pi)

# Euler's number (e)
x-equation: e^(t/60)

Advanced Functions

# Absolute value
x-equation: abs(sin(t/10))

# Square root
y-equation: sqrt(t)

# Logarithm
x-equation: log(t + 1)

# Min/Max
y-equation: max(0, sin(t/10))
x-equation: min(10, t)

Common Animation Patterns

Oscillating Movement

Smooth back-and-forth motion:

animations:
  duration: 60
  x-equation: 0
  y-equation: 3cos(t/30 * pi) # Bounces up and down

Circular Motion

Move in a circle:

animations:
  duration: 100
  x-equation: 20cos(t/50 * pi) # Horizontal circle component
  y-equation: 20sin(t/50 * pi) # Vertical circle component

Linear Movement

Straight movement:

animations:
  duration: 40
  x-equation: t * 2 # Moves right at 2 pixels per tick
  y-equation: 0

Bounce Effect

Bouncing animation using absolute sine:

animations:
  duration: 40
  x-equation: 0
  y-equation: abs(10sin(t/20 * pi)) # Bounces up from baseline

Fade In/Out

While BetterHud doesn’t have opacity control, you can simulate fading with scale or position:

animations:
  duration: 20
  x-equation: 0
  y-equation: (1 - t/20) * -100 # Slides up and disappears

Elastic Effect

Springy, elastic motion:

animations:
  duration: 60
  x-equation: 0  
  y-equation: 10 * e^(-t/20) * sin(t/5) # Dampened oscillation

Pulse Effect

Growing and shrinking:

animations:
  duration: 40
  x-equation: 5 * abs(sin(t/20 * pi))
  y-equation: 5 * abs(sin(t/20 * pi))

Popups have special movement animations:

my_popup:
  move:
    duration: 3 # Duration in seconds (not ticks!)
    pixel:
      x-equation: 0
      y-equation: 40t # Moves up over 3 seconds
  triggers:
    1:
      class: entity_attack
  layouts:
    # ... layout configuration

duration: Movement duration in seconds (not ticks)
pixel.x-equation: Horizontal movement
pixel.y-equation: Vertical movement

Slide Up

move:
  duration: 2
  pixel:
    x-equation: 0
    y-equation: 20t # Slides up 20 pixels per second

Slide Right and Fade

move:
  duration: 3
  pixel:
    x-equation: 30t # Slides right
    y-equation: 10t # Slides up slightly

Arc Movement

move:
  duration: 2
  pixel:
    x-equation: 15t
    y-equation: 20t - 10t^2 # Parabolic arc

Layout Animations

Layouts support repeating animations:

health_layout:
  images:
    1:
      name: health_bar
      x: 0
      y: 0
  animations:
    duration: 60 # Repeats every 3 seconds
    x-equation: 0
    y-equation: 3cos(t/30 * pi) # Gentle floating

Animation Timing

Loop Timing

Animations automatically loop based on duration:

animations:
  duration: 60
  # At t=0: animation starts
  # At t=60: animation loops back to t=0
  y-equation: sin(t/60 * pi) # Completes one sine wave per loop

Synchronization

Multiple elements can have synchronized animations:

layout_one:
  animations:
    duration: 60
    y-equation: sin(t/30 * pi)

layout_two:
  animations:
    duration: 60
    y-equation: sin(t/30 * pi) # Same timing = synchronized

Phase Offset

Create phase-shifted animations:

layout_one:
  animations:
    duration: 60
    y-equation: sin(t/30 * pi)

layout_two:
  animations:
    duration: 60
    y-equation: sin((t + 30)/30 * pi) # 180° out of phase

Performance Considerations

Equation Complexity

Simple equations perform better:

# Good - Simple
y-equation: sin(t/10)

# Okay - Moderate
y-equation: 5 * sin(t/10) + 3 * cos(t/15)

# Slower - Complex
y-equation: sin(cos(tan(t/10))) + sqrt(abs(t))

Animation Count

Limit simultaneous animations:

Keep layouts under 10 animated elements per screen
Use animations only where needed
Consider disabling animations for lower-end clients

Update Rate

Animation updates match the tick speed:

# config.yml
tick-speed: 1 # Updates every tick (20 TPS)

Higher tick speeds = smoother animations but more resource usage.

Advanced Techniques

Multi-Stage Animations

Create complex multi-stage animations with conditionals:

animations:
  duration: 100
  # First 50 ticks: slide in
  # Last 50 ticks: slide out
  x-equation: (t < 50) * t + (t >= 50) * (100 - t)
  y-equation: 0

Easing Functions

Create smooth easing:

# Ease in (starts slow)
y-equation: 10 * (t/60)^2

# Ease out (ends slow)
y-equation: 10 * (1 - (1 - t/60)^2)

# Ease in-out
y-equation: 10 * (t/60 < 0.5) * 2*(t/60)^2 + 10 * (t/60 >= 0.5) * (1 - 2*(1-t/60)^2)

Randomized Animations

Note: exp4j doesn’t have built-in random, but you can vary parameters:

# Different elements with different frequencies
element_1:
  animations:
    y-equation: sin(t/10 * pi)

element_2:
  animations:
    y-equation: sin(t/13 * pi) # Slightly different speed

Debugging Animations

Testing Equations

Test equations at different time values:

# At t=0: sin(0/30*pi) = sin(0) = 0
# At t=15: sin(15/30*pi) = sin(π/2) = 1  
# At t=30: sin(30/30*pi) = sin(π) = 0
# At t=45: sin(45/30*pi) = sin(3π/2) = -1
# At t=60: sin(60/30*pi) = sin(2π) = 0
y-equation: sin(t/30 * pi)

Common Issues

Animation doesn’t move: Check if equation varies with t
Animation too fast: Increase duration or decrease equation multiplier
Animation too slow: Decrease duration or increase equation multiplier
Equation error: Verify syntax and function names

Examples

Floating Health Bar

health:
  images:
    1:
      name: health_bar
      x: 0
      y: 0
  animations:
    duration: 60
    x-equation: 0
    y-equation: 3cos(t/30 * pi) # Gentle floating

damage_popup:
  move:
    duration: 2
    pixel:
      x-equation: 0
      y-equation: 40t # Floats upward
  duration: 40
  triggers:
    1:
      class: entity_attack

Spinning Compass

compass:
  images:
    1:
      name: compass_arrow
      x: 64
      y: 64
  # Note: BetterHud doesn't support rotation directly
  # This would need custom implementation

Wave Effect

wave_element:
  animations:
    duration: 80
    x-equation: 10sin(t/20 * pi)
    y-equation: 10cos(t/20 * pi) # Creates circular wave

Next Steps

Layouts

Apply animations to layouts

Popups

Animate popups

Triggers

Combine with triggers

Images

Animate image elements

Get Started

Core Concepts

Configuration

Platform Guides

Advanced

​Animation Basics

​Animation Properties

​Duration

​Equations

​Mathematical Functions

​Trigonometric Functions

​Basic Operations

​Mathematical Constants

​Advanced Functions

​Common Animation Patterns

​Oscillating Movement

​Circular Motion

​Linear Movement

​Bounce Effect

​Fade In/Out

​Elastic Effect

​Pulse Effect

​Popup Animations

​Popup Move Properties

​Popup Animation Examples

​Slide Up

​Slide Right and Fade

​Arc Movement

​Layout Animations

​Animation Timing

​Loop Timing

​Synchronization

​Phase Offset

​Performance Considerations

​Equation Complexity

​Animation Count

​Update Rate

​Advanced Techniques

​Multi-Stage Animations

​Easing Functions

​Randomized Animations

​Debugging Animations

​Testing Equations

​Common Issues

​Examples

​Floating Health Bar

​Damage Popup

​Spinning Compass

​Wave Effect

​Next Steps