itgmania212121/Docs/CourseFormat.txt

Complete Course Template

[[ Header Content ]]
-- Header Content is any course-defining data, such as the title, banner,
-- and other parameters.

#COURSE:My Course!;
--	The title of the course.

#COURSETRANSLIT:My Course, Translated!;
--	The title of the course, transliterated into english.

#REPEAT:YES;
--	If this is present, the course does not end.
--	Useful for endless & workout courses.

#LIVES:4;
--	The maximum(?) number of lives attainable in the course. Enabling this will
--	automatically force your course into an Oni course.

#BANNER:My Banner.png;
--	A banner for your course.

#BACKGROUND:My Background.png;
--	A background for your course. Currently only available in SM5 and sm-ssc.

#STYLE:SINGLE,VERSUS;
--	Denote which styles may be played on this course. This is useful for
--	cloning courses for doubles and single styles.

#METER:Beginner:3;
--	A custom-set meter for that course difficulty. You may set the difficulty
--	for Beginner, Easy, Medium, Hard, Challenge and Edit difficulties.

[[ Song Content ]]
-- Song Content makes up the entries in the course,
-- and also allows for timed modifiers.

-- Modifiers can be assigned in a variety of formats, the most effective three being the following:

1.) Repeated Modifier Block w/ Length:
#MODS:TIME:0.500:LEN:0.500:MODS:2x;
#MODS:TIME:1.500:LEN:0.500:MODS:0.5x;

2.) Nested Modifier Block w/ Length:
#MODS:
	TIME:0.500:LEN:0.500:MODS:2x;
	TIME:1.500:LEN:0.500:MODS:0.5x;

3.) Nested Modifier Block w/ Ends:
#MODS:
	TIME:0.500:END:1.000:MODS:2x;
	TIME:1.500:END:1.500:MODS:0.5x;

#GAINSECONDS:60.5;
--	The number of seconds gained before starting a song. This and #LIVES are
--	mutually exclusive: you can either have one, the other, or none: both
--	is not possible. This is meant to be used for Survival courses.

#SONG:*:Medium:2x;
-- #SONG can take quite a variety of parameters, of which may be useful to you
-- for testing or other purposes.
-- * is a wildcard item, meaning that StepMania will always pick a random song
-- for this part of the course.
-- You can also replace with BEST*,WORST*,GRADEBEST*, or GRADEWORST*, where * 
-- is a number to retrive the first of each category above.
#SONG:BEST1:Medium:2x;
-- As well as that, you may also do Group Random, like such:
#SONG:Dance Dance Revolution 8th Mix/*:Medium:2x;
-- If the above is not applicable, StepMania will search for the song title as best it can, depending on what you give it:
#SONG:Xepher:Medium:2x;
-- Will simply search the title of the song.
#SONG:DDR Supernova/Xepher:Medium:2x;
-- Will search for the exact directory.

-- #SONG can also apply different effects on each entry in the course by adding
-- special modifiers to the modifiers segment:
#SONG:*:Medium:showcourse;
-- For example, forces the course to never be hidden, noshowcourse being the
-- reverse of such.

-- nodifficult also exists to disable a player from changing difficulties, 
-- barring the player from making it easier or harder ( Gauntlets & Survivals
-- do not allow you to change difficulties ).

-- 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
-- These can be used in any combination and order.
-- 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.
--  - Commas, and other control characters (`#`,`;`, `=`, and `:`) can be used, 
--    but they must be escaped (like `\#`, `\,`, etc).
--  Example: 
#SONGSELECT:TITLE=Goin' Under,Springtime;  
#SONGSELECT:TITLE=thank u\, next;

--  GROUP= A list of one or more song groups, separated by commas.
--  Notes:
--  - The "group" refers to the directory name of the song group.
--  - Group names must be an *exact match*.
--  - Commas, and other control characters (`#`,`;`, `=`, and `:`) can be used, 
--    but they must be escaped (like `\#`, `\,`, etc).
--  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.
--  - Commas, and other control characters (`#`,`;`, `=`, and `:`) can be used, 
--    but they must be escaped (like `\#`, `\,`, etc).
-- 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.
--  - Commas, and other control characters (`#`,`;`, `=`, and `:`) can be used, 
--    but they must be escaped (like `\#`, `\,`, etc).
--  - 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 a dash `-`.
--  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 a dash `-`.
--  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 a dash `-`.
--  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.
--  One possible use for this would be to create a course to force you to play songs 
--  from certain groups that you likely haven't played before, by combining this with
--  the GROUP parameter, eg "#SONGSELECT:GROUP=In the Groove:SORT=FewestPlays,1;"
--  
--  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 of right now, the results from using this parameter aren't exactly accurate.
--    I can't quite work out how/why it makes the choices that it does.
-- 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;
#SONGSELECT:GROUP=Stepmania 5:MODS=Overhead;
#SONGSELECT:ARTIST=Kommisar:MODS=2x;
#SONGSELECT:GROUP=In The Groove:TITLE=Mouth;
#SONGSELECT:BPMRANGE=110-160:DIFFICULTY=Medium;