What is a Simfile?
A simfile is a file that contains all the information needed to play a song in StepMania, including:- Song metadata - Title, artist, banner, background
- Audio file - The music to play
- Timing data - BPM changes, stops, delays
- Step charts - The actual arrows/notes to play
Supported Formats
StepMania supports multiple simfile formats, each with different capabilities:.SM Format
The classic StepMania format. Simple, widely supported, single timing data.
.SSC Format
The modern format with per-chart timing, extended features, and more metadata.
Other Formats
Legacy formats: DWI, BMS, KSF, and others.
Course Format
Course files (.CRS) for creating song playlists and marathons.
Simfile Structure
Basic Directory Layout
A typical simfile directory contains:File Naming
- Audio files: MP3, OGG, WAV formats supported
- Images: PNG, JPG, BMP formats supported
- Banner dimensions: Typically 256x80 or 418x164 pixels
- Background dimensions: Any size, typically 640x480 or larger
Format Comparison
| Feature | .SM | .SSC | DWI | BMS | KSF |
|---|---|---|---|---|---|
| Per-chart timing | No | Yes | No | No | No |
| Multiple difficulties | Yes | Yes | Yes | No | No |
| BPM changes | Yes | Yes | Yes | Yes | Yes |
| Stops/Freezes | Yes | Yes | Yes | No | No |
| Delays | Yes | Yes | No | No | No |
| Warps | No | Yes | No | No | No |
| Background changes | Yes | Yes | Yes | Yes | No |
| Keysounds | Yes | Yes | No | Yes | No |
| Speed changes | No | Yes | No | No | No |
| Modern features | Limited | Full | No | No | No |
Choosing a Format
Use .SM when:
- Creating simple charts with standard timing
- Maximum compatibility is needed
- Working with older StepMania versions
- All difficulties share the same timing
Use .SSC when:
- Different charts need different timing
- Using advanced features (warps, speed changes, fakes)
- Creating complex gimmick charts
- Working with StepMania 5.0+
Use legacy formats when:
- Converting existing files from other simulators
- Maintaining compatibility with specific games
- Working with format-specific features
Converting Between Formats
SM to SSC
StepMania can automatically convert .SM files to .SSC:- Open the song in Edit Mode
- Save the chart
- StepMania will create a .SSC file with all data
SSC to SM
Limitations when converting:- Per-chart timing data is lost
- Advanced features (warps, speeds, fakes) are lost
- Only song-level timing is preserved
MSD Format
Both .SM and .SSC use the MSD (Music Simulation Data) format, which uses tags:- Tags start with
# - Tag names are case-insensitive
- Values end with
; - Comments use
//
Example:
Metadata Tags
Common tags used in all formats:Basic Information
Basic Information
#TITLE- Song title#SUBTITLE- Song subtitle/remix name#ARTIST- Song artist#GENRE- Music genre#CREDIT- Chart author/credit
Media Files
Media Files
#MUSIC- Audio file path#BANNER- Banner image path#BACKGROUND- Background image path#CDTITLE- CD title graphic path#LYRICSPATH- Lyrics file path
Timing
Timing
#OFFSET- Audio offset in seconds#BPMS- BPM changes (beat=bpm,beat=bpm)#STOPS- Freezes (beat=seconds,beat=seconds)#DELAYS- Delays (beat=seconds,beat=seconds)#TIMESIGNATURES- Time signature changes
Display
Display
#DISPLAYBPM- BPM to display (actual, range, or *)#SAMPLESTART- Preview start time#SAMPLELENGTH- Preview length#SELECTABLE- Whether song is selectable
Timing Data Format
Timing data uses beat-value pairs separated by commas:- At beat 0, BPM is 120
- At beat 64, BPM changes to 140
- At beat 128, BPM changes back to 120
Beat Numbering
- Beat 0 is the start of the song (after applying offset)
- One measure = 4 beats (in 4/4 time)
- Beats can be decimal (e.g., 64.500 = halfway through beat 64)
Next Steps
Learn .SM Format
Detailed .SM format specification and examples
Learn .SSC Format
Complete .SSC format reference with advanced features