Project OutFox Wiki
Project OutFox home View the OutFox Wiki source on GitHub Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Modifier Files

These simfiles have modifiers that are scripted to happen at various points of the song. The difficulty can range between “trivial to read” to “may as well memorize the chart”.

Often called “Modfiles” or “Modcharts”.

These usually use the FGCHANGES or BGCHANGES of a simfile to load the lua files (if any are used).

Disclaimer: Make sure you’ve got making a chart down before starting to make modcharts! Good mods can’t save a bad chart!

How to Apply Modifiers

There are a few ways to go about this, and it varys depending on what version of SM is being used.

ApplyGameCommand (SM3.95/oITG/nITG)

ApplyGameCommand is a GameState function that provides a way to send modifiers among other commands. The first paramter is the command type followed by the parameters. (In this case, a modstring) The second parameter is what player to apply the command (1 = player 1). If not specified, it applies to all players.

GAMESTATE:ApplyGameCommand("mod, *0.5 420 beat", 1)

While it’s still available in SM5 (including OutFox), it’s not recommended because it applies mods to the “Preferred” ModsLevel, which means modifiers apply instantly (no transition), and they persist outside of the simfile. SM5.2 Doesn’t even have this function available.

#MODS (Course files, SM3.95/oITG/nITG/SM5)

Old modfiles used to require going into marathon mode to play the scripted modifiers. Unlike most things, this is time-based due to charts being able to have stops.

#MODS:TIME=0.000:END=10.000:MODS=*0.5 420 beat;
#MODS:TIME=5.000:LEN=1.600:MODS=*2 50 stealth;

(ex: Beat starts at 0 seconds and ends at 10. Stealth turns on at 5 seconds and ends 1.6 seconds later)

Nowadays, this is considered obsolete in favor of lua-powered modifiers. It’s still usuable in SM5.

#ATTACKS (Simfiles, nITG/SM5)

Allows for the application of modifiers similar to what course files have. The syntax is exactly the same, just with MODS becoming ATTACKS.

#ATTACKS:TIME=0.000:END=10.000:MODS=*0.5 420 beat;
#ATTACKS:TIME=5.000:LEN=1.600:MODS=*2 50 stealth;

nITG accepts #ATTACKS or #MODS inside the .sm file, while SM5 only accepts #ATTACKS in sm & ssc.

These do not load in course mode, however.

ApplyModifiers (nITG)

A dedicated function for applying modifiers without needing the processing overhead and “mod, " that ApplyGameCommand does.

GAMESTATE:ApplyModifiers("*0.5 420 beat", 1)

Often used as a replacement for ApplyGameCommand in nITG modfiles.

PlayerOptions functions (SM5)

Every modifier has a setter function in PlayerOptions. This can be used in place of other functions. These are case-sensitive, though. If using strings, they’ll have to be parsed to make use of these functions.

local po = {GAMESTATE:GetPlayerState(0):GetPlayerOptions('ModsLevel_Song'), GAMESTATE:GetPlayerState(1):GetPlayerOptions('ModsLevel_Song')}
po[1]:Beat(4.2, 0.5)

SetPlayerOptions (SM5)

This function works by resetting the PlayerOptions for the given level, and setting it according to the string.

GAMESTATE:GetPlayerState(PLAYER_1):SetPlayerOptions('ModsLevel_Song', '*0.5 420 beat')

Because it resets PlayerOptions, it might not be so useful for applying scripted modifiers.

FromString (SM5.1 and onwards)

Like how ApplyModifiers is specifically for modstrings in nITG, FromString provides direct access to the string parser used for modifiers in ApplyGameCommand, and works very much like how ApplyGameCommand would.

local po = {GAMESTATE:GetPlayerState(0):GetPlayerOptions('ModsLevel_Song'), GAMESTATE:GetPlayerState(1):GetPlayerOptions('ModsLevel_Song')}
po[1]:FromString("*0.5 420 beat")

Modfile templates

Starting to make a modfile can seem really daunting if one does not know how to begin. Luckilly, there are many templates out there to help with creating modfiles.

Ones made for Open/NotITG and SM3.95 are usually done with .xml files, and some rare .lua files.

Ones made for SM5 are almost always .lua files.

StepMania 5-Based templates

OpenITG/NotITG/SM3.95 templates