Theme Element Library/Jacket Wheel

Several new DDR games and themes use a jacket wheel ("Cover Flow" style) for selecting music instead of the traditional title wheel and FadingBanner combination. If we replace the conventional MusicWheelItem with a custom Lua actor, we can use StepMania 5's jacket support to get the desired effect.

This is an adaptation of freem's Banner Wheel writeup. For a more in-depth code sample, see Midiman's Jacket Display Gist.

Jackets
StepMania 5 loads jackets automatically when they are listed in the .SSC file. This is the preferred way to specify a song jacket/square banner:
 * 1) JACKET:MySong-jacket.png;

Beyond this, it attempts to look for image files in the same directory which start with  or contain   or. As a last resort, StepMania will look in the directory for a square image. If none of these is found, then the song does not have a jacket.

The Song object provides two functions for retrieving information about the jacket. The  function will return true if a jacket was found and the file exists, or false otherwise. The  function will return the path to the jacket image, in a form that can be passed to one of the   functions.

Graphics
We need to modify the appropriate type of MusicWheelItem. For this example, we will modify the "MusicWheelItem Song NormalPart" graphic. When the music wheel item is being constructed, the StepMania core sends it a  message with parameters about the song that it represents. We can use this message to build the items however we want by implementing a  in Lua.

This  first checks to be sure the supplied song is valid. It will then load the jacket if it is found, fall back on a scaled version of the song background, then the banner, and if nothing is found it will load a default fallback image.

Other
See the MusicWheel and MusicWheelItem articles for information on the metrics and other graphics used to make the music selection wheel. These will function the same way regardless of how we implement the items.