todo: rewrite to not suck
KKI LABS // PUBLIC RELEASE

Custom Speed Mods
by AJ 187 of KKI Labs
Draft 1
Official Submission Date: June 20, 2008
[Lua script (v1.4)] [plaintext edition]

Abstract

Background

Speed mods have become a very pivotal part of rhythm game playing. However, it's not exactly easy to change speed mods for the layperson.

Conclusion

Custom speed modifiers are real and working, allowing people to add and remove speeds with ease.

Custom Speed Mods: Implementation and Analyzation

Problem: Create an easier way to allow users to edit their speed mod config.

Hypothesis: By using custom option rows defined in Lua as well as other techniques learned over the course of advanced StepMania theming, one can define a custom mod system that reads from a file.

Implementation: I had tried this before, but failed. I will not be covering that implementation here, like I normally would, since I overwrote it with the working solution.

Custom option rows are a pain to deal with sometimes. If you have a simple option row that only requires On/Off (like Reverse Judge) or can deal with numerical things, then you're in the clear.

However, once you start to do something like this, the playing field changes. Things get harder. You have to start accounting for things you've never had to mess with before.

The main differences between the initial and final implementations is the separator used.

Originally, a newline was going to be used to separate speed mods. However, this turned out to be a problem both cosmetically and functionality-wise. Cosmetically, an invalid character would show up after each line but the last. Since this was a part of the option's name, it also prevented every option but the last to be remembered.

A switch to spaces was made, followed by commas. These allowed the options to retain their names and be remembered later on.

Implementation Details
Before you begin, find SpeedMods.txt and set up your speed mods, separated by commas, i.e. "1x,2x,2.5x,3x,4x,8x,C200,C400" (no quotes).

I'm not going to repost the Lua code in here; feel free to look at CustomSpeedMods.lua, which should have been included with this guide.

SpeedMods() is pretty daunting to most people who have never worked with custom option rows before. Let's run through it:

GetSpeedMods() is a local function that:
  1. Reads in a file,
  2. Gets the speed mods from it,
  3. Puts the speed mods in a table,
  4. Returns said table, or a table with only 1x if the file was not found.
At this point, I would like to mention that the code included makes the custom speed mod code a theme-specific thing.

If you would like this to apply to all themes, change the value of path to "SpeedMods.txt".

This will put the file in the root StepMania directory.
It may work better in the Data directory. If you feel this way, change the line to the following: "Data/SpeedMods.txt"
Remember to copy/move the file to the new location or else you'll just get 1x.

Now we get to the real hard part, setting up the OptionRow.

First, a table is made. This will store all the information we need.

Now for LoadSelections. This is the first really hard part. LoadSelections is what's responsible for making sure options persist.

First, we get a list of the player's current modifiers. This is likely to contain a speed mod already.

Then we iterate through the choices we set before, using string.find on the mod string in order to find a choice that matches. If there is a matching choice, it's set to true and we return since we're not a MultiSelect row. If you were adapting this for a MultiSelect row, you'd remove the continue and move on.

If this isn't the case, then we set the first choice to true as a fallback, just in case anything goes wrong.

After LoadSelections comes SaveSelections. This does the task of adding the mod to the player. Unlike In-Song Modifiers, we do NOT need to account for the other mods here. This makes things really simple.

The logic is pretty simple here, since it's similar to LoadSelections.
We have the same loop through the choices, and if list[i] IS true, then we start to mess with the player options.

First, we get the PlayerState, then we SetPlayerOptions (Preferred since the player was the one who chose it) to self.Choices[i], and return. Again, if this was a MultiSelect row, you'd drop the return here.

Now, to implement it in the theme.

Find your ScreenPlayerOptions. If you have a row set for speed already (usually "list,Speed"), replace it with "lua,SpeedMods()". This will load the Lua-based OptionsRow instead of the normal StepMania-based one.

If you wanted this to take effect on all themes without custom option rows, then replace it in the default theme. Otherwise, replace it in whatever theme you like. Except dubaiOne. That's going to have it built in soon.