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

Documentation Index

​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