Tutorials:SM5 Theming Basics

This brief tutorial will help you grasp the basics on how to make themes targeted for StepMania 5. The following assumes you have read The Basics and will spare you little in preparation.

Constructing Basic BGAnimations In SM5
Lua is used to create things that work with SM5, as opposed to INI and XML BGAnimations from previous versions. Lua shares similar building style to XML, but both share similarities to how INI interfaces and adds commands to Actors. Consider the following examples of all 3 types of the languages used to show a graphic in the center of the screen.

Using BGAnimation Layers Properly
StepMania 5 includes a majority of new Screen layers, where graphics and items are placed in certain order above and below each other. Again, a comparison of each major version for clarity, where Screen is to be replaced with whichever screen you may be working with at the time:

3.9

 * Screen background
 * Screen overlay (only in very specific cases)

3.95, 4.0

 * Screen background
 * Screen underlay
 * Screen overlay

SM5

 * Screen background
 * Screen underlay
 * Screen overlay
 * Screen decorations

3.9 had you place whichever actors you would like to order in background only, with only overlay being an exception for very specific things. 3.95 added a lot of leniency, including the overlay and underlay layers on all screens. SM5 includes decorations, so themers can add things to the screen itself.

All in all, SM5 encourages the use of the background for actual background imagery that will never need to pop up over any other graphic. Underlay is for graphics that appear above the background as stylish content. Decorations are used for items that are particularly meant as part of the screen itself, including items such as StepsDisplay, GrooveRadar, DifficultyList, ScoreDisplay, and the like. Overlay is used mostly as the archetypical warning area, and is usually rarely used unless for that purpose or for anything that needs to be above everything.

Understanding Decorations
Decorations is by far the most unique feature of SM5. Decorations have specific scripts that let them request graphics and metrics and allow the themer to add behaviors to them.

Consider the following example from the default theme from SM5's ScreenWithMenuElements: Notice how most elements that are usually in all menu screens are defined here. If you were to remove these 3 Decoration declarations, you would be missing quite a bit of content from each screen.

Decoration declarations are simple functions that load metric commands for an object from its name (MetricName), and also request a graphic (GraphicName) from the Graphics folder.

When creating a new decorations layer for another screen, it's important to load the fallback decorations via LoadFallbackB: