Tutorials:Ini to Lua

If you already know how to theme for StepMania 3.9 and want to make themes for StepMania 5.0, there's a major difference in how BGAnimations and the like get made. In 3.9, you would use .ini files to define all the layers. In StepMania 5, this has been replaced with Lua.

Before continuing on, it is assumed that you have a basic knowledge of theming for 3.9. This guide will only list basic conversions; it will not talk about new layer types like, etc.

File Structure
With Lua, the BGAnimation is structured a bit differently. Where you have  in ini files, Lua requires a table to be returned. More often than not, this takes the form of a variable containing an ActorFrame (expressed in code as, with the ... being the body of the ActorFrame).

Compare the basic setups:

Lua
These two examples are the bare minimum you need for a working BGAnimation. It should be noted that you don't have to name it. You can name it whatever you wish, including,  , and so on. Just remember to change the return value as well.

Loading Files
The basic unit of a layer in the ini is, where the # can be any number. There are many things you can throw in these layers, but the most common are files.

Lua
In Lua, you use  (or any of the other layer types) to define a layer. There are other ways of defining a layer (as well as many other objects not normally callable in 3.9), but  is the most common.

First, a simple example, without any commands:

Note that you must put the file name in quotation marks and that the extension is optional. Generally, these go into the main  you set up at the beginning. In context, the entire file would look like:

However, you'll often want to add commands, so you need to add a few lines: The main thing to take away here is that commands are normally wrapped within. They don't always have to be, but it's simpler this way.

is just one of the few command types built in to StepMania. If you've worked with 3.9 before, you should be familiar with a few of these, mainly  (unused in SM5), , and. With this command added, the entire file looks like this:

Text
Usually, there were one of two ways you handled text in 3.9: .actor files and within the ini itself.

Lua
With Lua, the setup has changed a little bit: There is also a command  for use inside of commands, if you don't like using the   attribute.

Positioning
Positioning becomes an issue since StepMania 3.9 placed objects at  by default, whereas StepMania 5 places objects at. Be careful of this when porting themes. Otherwise, positioning has become more flexible in SM4, due to the existence of various  aliases. If you used absolute positioning before, it's a better idea to use relative positioning, either using the center of the screen or any of the sides.

The below table of equivalent positions operates on the assumption that your theme is set to 640x480. (See  in the metrics if you are not sure; if it doesn't exist in your theme, check the default.)

CommandRepeatSeconds
A useful command in 3.9 BGAnimations is CommandRepeatSeconds, which will allow you to specify how often the command should repeat. There is no direct substitute for this using Lua, so you have you think outside the box.

can take the place of CommandRepeatSeconds, assuming you time everything out. takes in one parameter, a string that represents the command to be queued up. Say you have. This will queue up the matching  on the target object. Note how the word "Command" was added to the end of the command name.

By combining  with, it's possible to get an equivalent effect to CommandRepeatSeconds.

Conditionals
Conditionals allow you to show or hide layers based on a Lua statement as described at Tutorials: Conditionals.

SM Ini to Lua Converter
SM Ini to Lua Converter is a Windows .NET program by Daisuke Master. It can convert a BGAnimation.ini file to Lua with the following restrictions:
 * Tile and Particle layer types are not supported.
 * Conditionals are not converted to the StepMania 5 equivalents.