BGAnimations Format

StepMania's BGAnimations have changed a lot over the years.


StepMania 5

StepMania 5 uses Lua for its BGAnimations.

Previous versions

StepMania 4 (.xml)

While also supporting .ini, StepMania 4's primary BGAnimation format was XML.

StepMania 3.9 (.ini)

StepMania 3.9 allowed for .ini files to create BGAnimations.

StepMania 3.0

The BGAnimations folder in the StepMania program directory may contain several BGAnimation folders.

\BGAnimations\<anim folder>\<layer files>

<anim folder> is the name of the animation.

<layer files> are one or more graphics files that will be used as layers in the animation. Each sprite represents exactly one layer. Multiple layers can be specified by having multiple <layer files>. Layer files can be PNG, AVI, or MPEG files.

For example, a BGAnimation named "flower" may include the files:

BGAnimations\flower\1 TileScrollUp.png BGAnimations\flower\2 StartOnRandomFrame ParticlesFloatDown 1x2.png BGAnimations\flower\3 TileScrollLeft CycleColor 2x2.png

The layers of a BGAnimation are drawn from bottom in the order in which the layer graphics files appear alphanumerically. A layer file name will often begin with a number to control the order in which they are drawn.

Different "effects" are specified for each layer by adding tokens to the file name. Here are an explanation of the currently supported tokens:

  • UseSongBg - Use the song's background file instead of this graphics file. Since this graphics file is merely a placeholder, you might want to make this graphic a 1x1 graphic to save disk space.
  • Add - use additive blending instead of normal blending.
  • CycleColor - cycle the color of the layer over the colors of the rainbow
  • CycleAlpha - cycle the alpha channel of the layer over type
  • StartOnRandomFrame - Start the animation on a random frame. This is mainly useful for Tile or Particle effects.
  • DontAnimate - Stay on the first frame of this animation. This is only useful for layers with multiple frames.
  • Stretch Effects - These scretch the graphic across the extire screen.
    • ScretchScrollLeft, StretchScrollRight, StretchScrollUp, StretchScrollDown - Scroll the layer in a direction
    • StretchWater, StretchBubble, StretchTwist, StretchSpin - Deform the background sprite with an effect. Only stretch spin is currently implemented.
  • Particle Effects - Use the graphic to make individual particles on the screen.
    • ParticlesSpiralOut, ParticlesSpiralIn - Spiral particles away from/toward the center of the screen.
    • ParticlesFloatUp, ParticlesFloatDown, ParticlesFloatLeft, ParticlesFloatRight

- Scroll the particles across the screen.

    • ParticlesBounce - Particles start traveling in random directions and bounce when they hit the edge of the screen.
  • Tile Effects - Tile the graphics across the screen, forming a grid of graphics.
    • TileStill, TileScrollLeft, TileScrollRight, TileScrollUp, TileScrollDown - Scroll the tiles
    • TileFlipX, TileFlipY - Flip the tiles along the X or Y axis.
    • TilePulse - Tiles zoom in and out.

Thanks to (donated web hosting)