Preferred Sorting - CrashCringle12/Simply-Love-SM5 GitHub Wiki

Understanding Preferred Sort

Preferred Sorting is a way to create custom song groups (known as "Sections") in the Music Wheel without needing to rearranging the physical location of the songs on your device. The most common use case for leveraging Preferred Sorting is alleviating the need to create a new pack just to have a place to access specific songs (such us creating a "Favorite Songs" pack, creating packs to act as "Playlists", or creating tournament packs that use songs already present on the machine).

Preferred Sorting is a feature originally present in StepMania 5 that has seen improvements in ITGMania. For information specifically on SM5 preferred sorting please refer to: https://github.com/stepmania/stepmania/wiki/Preferred-Sort. Going forward this document will discuss Preferred sorting as it applies to ITGMania.

Preferred sorting allows you to defien a custom order for displaying songs in the music wheel. It relies on a text-based files which specify which songs to include, how they should be grouped, and their exact display order.

Structure of a Preferred Sort File

The format is as follows:

---Section Name
SongGroup/SongFolder   # Explicitly define a song from a specific group
SongTitle              # Implicitly define a song 
SongGroup/*            # Include all songs from a specific group
  • --- starts a new section (displayed as a sub-category in the music wheel).
  • Sections continue until another --- appears or until the end of the file.
  • You must have at least one section defined in the file for it to be parsed correctly.
  • SongGroup refers to the name of the song's pack folder as it is written on disk (This may be different from the pack's displayed title)
  • SongFolder refers to the name of the song folder as it is written on disk (This may be different from the song's displayed title)
  • SongTitle refers to the song's folder (above) or it's {TITLE} {SUBTITLE} (using transliterated titles first if available)
  • The wildcard * includes every song within the specified group.
  • Lines with either a missing or invalid song (due to typos or non-existent folders) are simply ignored without causing errors.
  • A section named Unlocks will appear at the very bottom if you've utilized the engines Unlock System and have unlocks on your profile (This is not related to SRPG/ITL at this time)
  • Individual songs are found by using SONGMAN->FindSong() under the hood.

Here is an example:

---Penn State Local Tournament 1
UPS 3/Mouse Dance
Easy As Pie 6/*
FA and Chill 2/BIPP
Lips Are Movin
---Penn State Local Tournament 2
AJAX's Small Assortments/[AJAX] Better Off Alone
FA and Chill 2/*
Cringle Conservation/call me maybe
J.U.M.P.S. 2/*
---Penn State Local Tournament 3
Cringle Asylum/*
UPS 4/wah-propaganwah (habstrakt remix) (ddrillini remix)

In this example this sort will have 3 Sections called Penn State Local Tournament 1, 2, and 3. The first section will be called "Penn State Local Tournament 1" and have Mouse Dance from UPS 3, the entirety of the Easy As Pie 6 pack, BIPP from FA and Chill 2, and the first song found that is called Lips are Movin.

Using Preferred Sort

There are two* ways a theme can set the preferred sort:

Setting via Lua

On ScreenSelectMusic, you will need to change the SortOrder to SortOrder_Preferred and additionally use SONGMAN:SetPreferredSongs() to specify the name of your preferred sort. This method has two parameters as described here. The isAbsolute parameter allows for ITGMania to maintain backwards compatibility with SM5. This means if SetPreferredSongs() is used without its second parameter set as true, you MUST prefix your file with SongManager and place it in your theme's Other folder.

SCREENMAN:GetTopScreen():GetMusicWheel():ChangeSort("SortOrder_Preferred"); // Changes the SortOrder to Preferred
SONGMAN:SetPreferredSongs("NameOfMySort.txt"); // Specifies the name of the file defining the songs/sections in our desired preferred sort.

Where this would attempt to use {Theme Folder}/Other/SongManager NameOfMySort.txt as my preferred sort.

SCREENMAN:GetTopScreen():GetMusicWheel():ChangeSort("SortOrder_Preferred"); // Changes the SortOrder to Preferred
SONGMAN:SetPreferredSongs("./path/to/NameOfMySort.txt", true); // Specifies the absolutePath of the file defining the songs/sections in our desired preferred sort.

Where this would attempt to use ./path/to/NameOfMySort.txt as my preferred sort.

Metrics way

Place your desired text file in the Other folder of your theme and ensure it is explicitly named SongManager PreferredSongs.txt.

In the [GameState] section of your metrics.ini, add DefaultSort="Preferred". (This metrics value is also in ScreenSelectMusic but it doesn't do anything there, so ignore it)

Frequently Asked Questions (FAQ)

  • Q: How does ITGMania determine song order within a section?
    A: By default, songs appear exactly in the order listed in the file.

  • Q: How does ITGMania determine section order?
    A: Sections will appear exactly in the order listed in the file.

  • Q: What happens if a song is listed in the file but is not found?
    A: This line will simply be ignored, no errors will be thrown.

  • Q: What happens if I don't put any sections in the file?
    A: The file will be read as having no songs listed.

  • Q: Is there a way to test if a line will find the song?
    A: Yes, you can use SONGMAN:FindSong(line). Where line is a line as you've written in the file. If this method returns a song, then Preferred Sort will be able to locate it.

  • Q: What is the format for the file? Are there any special characters?
    A: Yes, please see the "Structure of a Preferred Sort File" section above.