Project OutFox contains a parser for the SM chart format, which has existed as early as StepMania 3.9, and is what most StepMania-based engines support as a base format & simfile cache format. With SM5, this has been succeeded by the SSC format, but for completeness, the following page contains details about what the SM format supports and used to support.
Every section follows this format: #SECTION:DATA;, which means #, ; and : shouldn't be used in the data section.
To note, some sections parsed are from SSC, so the current implementation of SM is both SM and a bit of SSC.
TITLEThis gives the title of the song.
If not defined, the game falls back on the simfile directory name.
Example:
#TITLE:Blow My Mind;
SUBTITLEThis gives the subtitle of the song. It's often shown underneath the song title.
If TITLE wasn't defined, the game falls back on the simfile directory name for this as well.
Example:
#SUBTITLE:Tournament Stage 2;
ARTISTThis gives the artist of the song.
If not defined, the game shows "Unknown artist" instead.
Example:
#ARTIST:かめりあ;
TITLETRANSLITThis is the transliterated song title that usually shows when the ShowNativeLanguage preference is on.
Some music wheels use this if the font used doesn't have the characters needed for the main title.
If empty, the TITLE section is used in all cases.
Example:
#TITLETRANSLIT:Ame agari no uta;
SUBTITLETRANSLITThis is the transliterated subtitle that usually shows when the ShowNativeLanguage preference is on.
Some music wheels use this if the font used doesn't have the characters needed for the main title.
If empty, the SUBTITLE section is used in all cases.
Example:
#SUBTITLETRANSLIT:Touhou Koumakyou;
ARTISTTRANSLITThis is the transliterated song artist that usually shows when the ShowNativeLanguage preference is on.
Some music wheels use this if the font used doesn't have the characters needed for the main title.
If empty, the ARTIST section is used in all cases.
Example:
#ARTISTTRANSLIT:Camellia;
GENREThis is the genre of the song. Some examples are Rock, Dubstep, and Classical. Anythng can be put here as a genre.
Example:
#GENRE:Techno Pop;
CREDITThis field is for crediting someone, usually the author of the chart
Example:
#CREDIT:Narumi;
BANNERThis defines the file to use for the song's banner. It's usually in the same folder as the simfile. This is a relative path.
If not defined, the game looks for image files that contain "banner" or end with "bn".
Example:
#BANNER:crazy-bn.png;
BACKGROUNDThis defines the file to use for the song's background. It's usually in the same folder as the simfile. This is a relative path.
If not defined, the game looks for image files that contain "background" or end with "bg".
Example:
#BACKGROUND:awesome-image.png;
LYRICSPATHThis defines the file to use for the song's lyrics. This is a relative path.
Example:
#LYRICSFILE:speed.lrc;
CDTITLEThis defines the file to use for the song's CD Title. Usually the simfile author uses this to put their author image. This is a relative path.
Example:
#CDTITLE:nonsense.png;
MUSICThis defines the file to use for the song's music. This is usualy in the same folder as the simfile. This is a relative path.
Example:
#MUSIC:dondadon.ogg;
INSTRUMENTTRACKSpecifies a song file to use for an instrument track. This is a relative path. Valid intrument tracks are: "Guitar", "Rhythm", "Bass", "Vocal", "Drum1", "Drum2", "Drum3" and "Drum4"
Example:
#INSTRUMENTTRACK:track1.ogg=Guitar,
track2.ogg=Drum1;
SAMPLESTARTDefines the starting point of the same taken from the main audio file, in seconds.
Example:
#SAMPLESTART:20.421;
SAMPLELENGTHDefines how long the song's sample plays for, in seconds.
Example:
#SAMPLELENGTH:5.000;
DISPLAYBPMSets the BPM to be shown in the music wheel.
* means it's random, and constantly changing characters are shown for BPM.
If not set, the song's min and max BPM are shown instead.
Example:
#DISPLAYBPM:240;
or
#DISPLAYBPM:*;
SELECTABLESets whether the song is shown in the music wheel or not. This is ignored if the HiddenSongs preference is turned off.
"YES", "1", "ES"(3.9+) and "OMES"(3.9+) are the same, while "NO" or "0" set it to unselectable.
Example:
#SELECTABLE:NO;
BGCHANGES / BGCHANGES2 / BGCHANGES3 / ANIMATIONSSpecifies what the background of a song changes to throughout the chart. This allows lua files to be loaded.
BGCHANGES with numbers specifies what layer it shows up on. (BGCHANGES2 = Layer 2)
BGCHANGE format:
beat=file_or_folder=update_rate=crossfade=stretchrewind=stretchnoloop=Effect=File2=Transition=Color1=Color2
red^green^blue^alpha, with the values being from 1 to 0, Passed to the BackgroundEffect with the LuaThreadVaraible "Color1"/"Color2" in web hexadecimal format as a string. Alpha is optional.Often, a last entry with "-nosongbg-" as the file is placed so the song's starting background doesn't show up at the end.
Example:
#BGCHANGES:0.000=blossom1.jpg=1.000=1=0=1===CrossFade==,
52.000=blossom2.jpg=1.000=0=0=1=====,
164.000=blossom1.jpg=1.000=0=0=1=====,
229.000=blossom3.jpg=1.000=0=0=1=====,
302.000=blossom1.jpg=1.000=0=0=1=====,
99999=-nosongbg-=1.000=0=0=0 // don't automatically add -songbackground-
;
The second line explained: 52.000=blossom2.jpg=1.000=0=0=1=====
FGCHANGESLike BGCHANGES, FGCHANGES follow the same format, but happen in a Foregound layer, above the players and most everything else. Commonly used in gimmick files to script modifiers or other visual aspects.
Example:
#FGCHANGES:0.000=lua=1.000=0=0=1=====;
KEYSOUNDSSpecifies what files to load as keysounds. Uses relative paths.
Example:
#KEYSOUNDS:pf_24_c#+.ogg,ba_op1.ogg,dr_hho.ogg,dr_rs.ogg,dr_bd8.ogg,dr_cs8.ogg,sq_a.ogg,pc_c.ogg,pf_op11.ogg;
OFFSETDefines when beat 0 starts, in seconds. Charts made for the ITG meta tend to have an extra positive 9 ms added.
Example:
#OFFSET:-0.611000;
STOPS / FREEZESDefines where stops in the song happen. The first parameter is the beat, and the second parameter is how long the stop is, in seconds.
Example:
#STOPS:46.250000=0.030000,
46.500000=0.030000,
46.750000=0.030000;
BPMSDefines the BPMs the song has. A song must have at least one BPM at beat 0.
The first parameter is the beat, and the second parameter is the actual BPM.
Example:
#BPMS:0.000=140.250,
48.000=93.500,
48.333=62.333;
TIMESIGNATURESDefines the time signatures of the song. Most songs default to 4/4 as their starting signature. There are three parameters: beat, numerator and denominator. The last two parameters must be greater than or equal to 1.
Currently, this only affects the measure lines.
Example:
#TIMESIGNATURES:0.000=4=4;
ATTACKSThese are course-style scripted modifiers written into the simfile. Unlike most sections, this is seconds-based instead of beat-based, to allow for modifiers during stops.
The format of an attacks entry is this:
TIME=seconds:END/LEN=endtime/lengthtime:MODS=modstring
Internally, entries that use END are converted into LEN.
Example:
#ATTACKS:TIME=1.618:END=3.166:MODS=*32 Invert, *32 No Flip
:TIME=2.004:END=3.166:MODS=*32 No Invert, *32 No Flip
:TIME=2.392:LEN=0.1:MODS=*64 30% Mini
:TIME=2.489:LEN=0.1:MODS=*64 60% Mini;
DELAYSSpecifies the Delay segments for the song.
The first parameter is the beat, and the second parameter is the duration in seconds.
Appears to have been added since SM-SSC.
Example:
#DELAYS:488.000=0.050;
TICKCOUNTSSpecifies how many checkpoints a hold has in a beat.
The default value is 4. This only gets used in the pump game mode.
The first parameter is the beat, and the second parameter is the number of checkpoints to use.
Appears to have been added since SM-SSC.
Example:
#TICKCOUNTS:0.000000=4,
50.000=16;
NOTES / NOTES2NOTES2 is written when keysounds are used, but both are read in the same way.
Notedata has 6 parameters:
game-style. eg: pump-doublesThere are two special cases involving the Hard difficulty. If the description is "smaniac" or "challenge", it gets read into the Challenge difficulty.
Each measure has a minumum of four lines, with each measure being comma separated. The number of characters per row corresponds to the number of columns the mode has. (eg: dance-single has four columns, so each row has four characters)
4 rows per measure allows for 4ths, 8 rows per measure allows for 8ths, 16 rows per measure allows for 16ths, etc.
The following table shows what character corresponds to what note type (not including characters introduced by SSC)
| Note Character | Note Type | Quirks |
|---|---|---|
| 0 | empty | N/A |
| 1 | Tap Note | N/A |
| 2 | Hold Note Head | N/A |
| 4 | Roll Note Head | N/A |
| 3 | Hold & Roll Note Tail | Having a 3 without a corresponding 2 or 4 will result in warnings. |
| M | Mines | N/A |
| K | AutoKeysounds | N/A |
| L | Lifts | N/A |
| F | Fakes | They can only be fake taps. You can't do fake holds with this. |
Attacks can be attatched to notes by having {} after the note.
The format is {modstring:lengthseconds}
When hitting a note with an attack, the attack gets applied for the player as a whole for the given duration.
Keysounds can be attached to a note by having [] after the note.
The format is [index], with index starting at 0, and corresponding to the order listed in #KEYSOUNDS.
Example:
#NOTES:
dance-single:
Charter Man:
Easy:
4:
0.503,7.2,0,0,0:
L000
00F4
0000
0003
,
1000
0200
00M0
A[0]000
0300
0000
0001{tipsy,50%bumpy:5.2}
0000
;
These sections are considered unused or ignored in normal simfiles due to being replaced, removed or being used in cache files instead.
MUSICLENGTHSpecifies how long the music is, in seconds.
Used in the cache variant of the SM format.
Example:
#MUSICLENGTH:64.052;
MUSICBYTESJust flat out ignored. No-one seems to know what this was for.
LASTBEATHINTSpecifies a custom last beat for the song. Phased out at some point.
Example:
#LASTBEATHINT:211.000000;
FIRSTBEATSpecifies the first beat in the song.
Used in the cache variant of the SM format. Phased out at some point.
Example:
#FIRSTBEAT:10.348;
LASTBEATSpecifies the last beat in the song.
Used in the cache variant of the SM format. Phased out at some point.
Example:
#LASTBEAT:128.600;
SONGFILENAMEThe full path to the simfile itself.
Used in the cache variant of the SM format. Moved into the SSC cache format.
Example:
#SONGFILENAME:/AdditionalSongs/UPS 4/Brain Power/Noma - Brain Power.sm;
HASMUSICUsed in the cache variant of the SM format. Moved into the SSC cache format.
Example:
#HASMUSIC:1;
HASBANNERUsed in the cache variant of the SM format. Moved into the SSC cache format.
Example:
#HASBANNER:0;
SAMPLEPATHDefines the path to the separate sample audio. Phased out at some point.
LEADTRACKUnknown.
Written and Maintained with ♡ by MTK