Added description for the new #SONGSELECT course tag.

Docs/CourseFormat.txt

@@ -86,13 +86,149 @@ Complete Course Template
 -- Finally, award*, where * is a number, allows you to control how many lives
 -- the player gains from successfully completing a course in Oni mode.
 
+
+
+#SONGSELECT:GROUP=Stepmania 5:BPMRANGE=120..160:Difficulty=Medium:MODS=2x;
+-- #SONGSELECT is a new alternative to the #SONG tag, which will (hopefully)
+-- be easier to use and understand. Instead of relying on values input in a
+-- very specific and poorly-documented order, this tag is composed of 
+-- a series of PARAM=VALUE statements, separated by :'s. 
+
+-- The following parameters are available for selecting a song:
+-- TITLE, GROUP, ARTIST, GENRE, DIFFICULTY, METER, BPMRANGE, DURATION, SORT
+-- With the exception of SORT, these can be used in any combination and order.
+-- (See the SORT parameter description below for a better explanation)
+-- If none are specified, then a song and difficulty will be chosen completely at random.
+-- If a combination is specified that results in no possible songs to select,
+-- then that #SONGSELECT entry is skipped.
+
+-- Parameter Desciptions:
+--  TITLE= A list of one or more song titles, separated by commas.
+--  Notes: 
+--  - The "title" here can be either the name of the song directory,
+--    the #TITLE, or the #TITLETRANSLIT.
+--  - Titles must be an *exact match*.
+--  - Unlike the #SONG tag, this will not take into account group names.
+--    If you want to specify a specific song from a specific group, use
+--    this along with the GROUP parameter.
+--  - This does not support names that have commmas.
+--  Example: 
+#SONGSELECT:TITLE=Goin' Under,Springtime;  
+
+--  GROUP= A list of one or more song groups, separated by commas.
+--  Notes:
+--  - The "group" refers to the directory name of the song group.
+--  - This does not support folders that have commas in their name.
+--  - Group names must be an *exact match*.
+--  Example: 
+#SONGSELECT:GROUP=Stepmania 5,In The Groove;
+  
+--  ARTIST= A list of one or more artist names, separated by commas.
+--  Notes:
+--  - The "artist" refers to either the #ARTIST or #ARTISTTRANSLIT value
+--    of the simfile.
+--  - This does not support artist names that contain commas.
+-- Example:
+#SONGSELECT:ARTIST=Kommisar,NegaRen;
+
+--  GENRE= A list of one or more song genres, separated by commas.
+--  Notes:
+--  - The "genre" refers to the #GENRE tag of a song.
+--  - Most songs don't actually have a #GENRE defined, which unfortunately
+--    makes this parameter not terribly useful at this time.
+-- Example:
+#SONGSELECT:GENRE=J-Pop,Black Metal;
+
+--  DIFFICULTY= A list of one or more difficulties, separated by commas.
+--  Notes:
+--  - There are a number of acceptable values for this, but for the sake
+--    of consistency, please try to use:
+--    Beginner,Easy,Medium,Hard,Challenge,Edit
+--    (if you really want to use whacky value names, you can find the rest
+--     defined in Diffiulty.cpp)
+--  Example:
+#SONGSELECT:DIFFICULTY=Medium,Hard;
+
+--  METER= A minimum and maximum value of a song's difficulty meter,
+--  separated by EXACTLY TWO (2) periods.
+--  Notes:
+--  - This is independent of the DIFFICULTY parameter, which can be used
+--    along with METER to further refine a specific song hardness.
+--  - If DIFFICULTY is not specified, then any difficulty may be picked from
+--    a song that matches the given range.
+--  - These values must be whole numbers.
+--  - These values are inclusive, meaning that song with a meter that is exactly
+--    the value of minimum or maximum can be chosen.
+--  Example:
+#SONGSELECT:METER=8..12;
+
+--  BPMRANGE= A minimum and maximum value of a song's bpm, 
+--  separated by EXACTLY TWO (2) periods.
+--  Notes:
+--  - The "bpm" values refer to the displayed bpm value/range of a song.
+--    This means that a song may be chosen if its #DISPLAYBPM matches the 
+      given range, even though it's true bpm might not.
+--  - These values should only whole numbers (no decimal places).
+--  - If a song has a displayed bpm range, both the min and max values must
+--    be within the specified range.
+--  - This range is inclusive, meaning that a song with a bpm that is exactly
+--    the value of the lower or upper range can also be chosen. 
+--  - This also means that if you want to choose songs of a very specific bpm,
+--    like songs that are exactly 120 bpm, you can specify BPMRANGE=120..120
+-- Example:
+#SONGSELECT:BPMRANGE=120..150;
+
+--  DURATION= A minimum and maximum value, in seconds, for the length of a song,
+--            separated by EXACTLY TWO (2) periods.
+--  Notes:
+--  - The "duration" values refers to either the song file's actual length, or
+--    The simfile's #MUSICLENGTH value, if specified.
+--  - These values should only be whole numbers (no decimal places).
+--  - This range is inclusive.
+--  Example:
+#SONGSELECT:DURATION=90..125;
+
+--  SORT= A set of two values that specify a sort type and a number, separated
+--  by a comma. For example, SORT=MostPlays,1 selects the #1 most played song on
+--  the machine, SORT=LowestGrades,10 selects the song that you've gotten your 10th
+--  worst score on.
+--  Notes:
+--  - Like DIFFICULTY, there are several acceptable values that are equivalent to each other.
+--    The old style values are Best, Worst, GradeBest, or GradeWorst. 
+--    For the sake of consistency and clarity, please consider using:
+--    MostPlays, FewestPlays, TopGrades, or LowestGrades.
+--  - The number value can be between 1 and 500.
+--  - As noted at the beginning of the description of #SONGSELECT, this parameter isn't
+--    really intended to be used with other selection parameters.
+--    It's not really accurate to say that it *can't* be used with them, but you're much
+--    more likely to find yourself with an entry that can't select any songs.
+-- Example:
+#SONGSELECT:SORT=MostPlays,4;
+
+-- Besides the selection parameters, there are a few more parameters added to make sure that
+-- this can be a complete replacement for the #SONG tag.
+-- These parameters are:
+-- MODS, GAINSECONDS, GAINLIVES
+
+--  MODS= A list of modifiers that are applied to the entire song.
+--  Notes:
+--  - This does *NOT* replace the #MODS tag for specifying timed mods/attacks.
+--  - At ths time, I don't actually know what all can be specified as a modifier.
+
+--  GAINSECONDS= The number of seconds gained before starting a song.
+--  This is exactly the same as if specifying the #GAINSECONDS tag.
+
+--  GAINLIVES= The number of lives gained for completing this song. 
+--  This is equivalent to the 'award*' modifier for #SONG. 
+
 Finally, here's an example course:
+
 #COURSE:My Awesome Course - The Revenge;
 #METER:Medium:8;
 
 #MODS:
 	TIME:1.00:END:50.00:MODS:C150;
-#SONG:In The Groove/Dawn:Overhead;
-#SONG:In The Groove/Mouth:;
-#SONG:In The Groove 2/Funk Factory:;
-#SONG:In The Groove 3/Disconnected Zeo:;
+#SONGSELECT:GROUP=Stepmania 5:MODS=Overhead;
+#SONGSELECT:ARTIST=Kommisar:MODS=2x;
+#SONGSELECT:GROUP=In The Groove:TITLE=Mouth;
+#SONGSELECT:BPMRANGE=110..160:DIFFICULTY=Medium;