Documentation on the KSF Format
-------------------------------
The KSF format is designed for representing steps for 5 panel diagonal
dancing games, such as Pump It Up. It was originally used in the Kick It Up
simulator, but can also be parsed by other programs. However, this seems
to be the only actual format description available.

The intention of this document is not to encourage creation of KSF files.
I believe the format to be broken, and provide this reference only for
people wishing to implement legacy file readers. Any new 5 panel dancing
patterns should use a well-defined format such as .dance or .sm.

Directory Layout
----------------
KSF filenames are case-insensitive.

A KSF directory contains the following files:

- At least one file matching *.KSF, containing the step data.
- A file named SONG.MP3, SONG.WAV, or SONG.OGG.
- A file named INTRO.MP3, INTRO.WAV, or INTRO.OGG, containing a sound clip,
  used to preview the song in song selectors.
- Disc.bmp, a 300x200 image used in song selectors.
- Back.bmp or Title.bmp, a 640x480 image used as a background during the song.

KSF directories may not have a special naming format, but some simulators
will use the directory name to get the artist and title name, if it's not
available in the KSF files themseleves. The format is "Title",
"Title - Artist", or "Title - Artist - Difficulty". Difficulty can be
ignored here, as it can be gotten from the KSF filename. Using the path
name to determine the metadata for the song should only be used if it's
not available in #TITLE.

Concievably other audio or image formats could be used. None have been
seen in the wild.

KSF Filenames
-------------
KSF filenames describe the game type and difficulty. Each file holds the
data for only one level of difficulty. There are two possible forms of
the name: *<gametype>*.ksf, or *<difficulty>_<playernumber>*.ksf.

The first type is used for double mode, and half-double mode. Double.ksf
contains the steps for "Double" mode, where one player uses both paths.
Stepmania supports Halfdouble.ksf, which ignores the outer 4 panels.

The latter type is used for single ("unison", which is not the same
as Dance Dance Revolution's Unison mode in early mixes) steps, where both
players have the same steps, and couple steps, where players have different
ones. If the player number is 1, they are single steps; if it's 2, they're
couple steps. Difficulty is a difficulty name.

KSF Headers
-----------
The basic KSF format is similar to DWI, SM, and MSD. Metadata is given
in the format of:
#TAGNAME:VALUE;

The exception being the #STEPS tag, which has a newline between the ":"
and the first line of steps, and ends on a line containing at least one
"2" among 13 characters.

KSF files seem to use CRLF (Windows-style) line termination. The vast
majority of KSF files are in CP942/KSC 5601 encoding, but some are
in EUC-KR. If ASCII alternatives are needed for these encodings, the
path name must be checked as above.

Common headers in KSF files are as follows:

#TITLE: The artist and title of the song, and sometimes the difficulty.
These are separated by " - "s, so the format is either "Title",
"Artist - Title", or "Artist - Title - Difficulty". Information missing
from this line can be filled in via path or file names.

#BPM: The BPM of the song. This is analogous to the BPM value for every other
dance format.

#STARTTIME: The time into the song to offset events, in centiseconds. This
is the opposite of .dance's gap and .sm's offset, and the same as .dwi's
gap (although they use different units).

#TICKCOUNT: Each step line specifies 1/TICKCOUNT beats. That is, if
TICKCOUNT is 1, each line is the equivalent of a 'q' in .dance. If it's
2, each line is the same as a normal length note in DWI (an 'e' in .dance).

#STEP: Until a line of "2222222222222" is encountered, each line after this
one represents a set of steps.

Step Lines
----------
Each line in the step section represents one "line" of steps, like SM
or .dance. Each line is 13 digits long; in single (unison) modes, only the
first 5 are used; in couple and double, the first 10 are used.

The order of the steps is Down Left, Up Left, Center, Up Right, Down Right.
The second player's (or second pad in double) steps are the same order,
but in positions 6-10 instead of 1-5.

A 0 in a position indicates no step. A 1 indicates a regular step. A 4
indicates a hold, for as long as a 4 is found in that column. The hold
ends on the beat of the last 4, not on the first 0.

Some files have been seen with repeated '1's in this manner as well;
it is unknown if any dance simulator supports this use of KSF, and since
a perfectly good non-ambiguous means of representing holds is available,
its use is not recommended.

A 2 (or a line of 13 2s) indicates the end of the step pattern.

BPM Changes
-----------
BPM changes are handled by header values; they are specified by a pair
of values #BPMx and #BUNKIx, where x is an integer. An example is:

#BPM:146.10;
#BPM2:180.20;
#BPM3:195.00;
#TICKCOUNT:2;
#STARTTIME:0;
#BUNKI:4200;
#BUNKI2:10000;

BPMn+1 starts at the time specified in centiseconds by BUNKIn (where n
is omitted if it is 1). In the above, 42 seconds (4200 centiseconds)
into the song, the BPM changes from its initial 146.1 to 180.2, and
then 100 seconds into the song, from 180.2 to 195.

BUNKIs can be a decimal value.

STARTTIME
---------

STARTTIME tags control the offset of the chart. The chart will begin at
the start of the music + the value of the STARTTIME (in centiseconds).

STARTTIME2 and STARTTIME3 are the values that the offset is set to at
the BUNKI and BUNKI2 points respectively. The chart position is moved
as if the chart started at that offset.

This allows for warps and other wonderful visual tricks like that, 
but Direct Move and StepMania don't properly implement this feature. 
Most KSFs don't use these tricks, thankfully, but you can find some 
that do; famously three or so made by Turkeyslam a very long time ago.

Syntax Exceptions
-----------------
Unlike DWI files, KSF files seem to have few exceptions or violations of
their syntax in the files seen in the wild. This may be because the format
is so mind-numbingly stupid.

Still Unknown
-------------

KSF step lines are 13 digits wide; only 10 digits appear to specify steps,
but the last 3 are not always 0. They are probably light control 
columns, but no dedicated KSF players support lights and SM won't load
lights from these channels. There are no KSFs known to use them properly.

Author
------
This document was written by Joe Wreschnig <piman@debian.org>. It is
released into the public domain.

Changes
-------
2003.08.15
 - Initial check in / release.
2011.10.31
 - Describe STARTTIME, change various other info.

Acknowledgements
----------------
This document is based primarily off of extensive work done by Matt Reppert.
The Stepmania KSF loader source code (src/NotesLoaderKSF.cpp) also proved
useful in verifying some information. The STARTTIME behavior was found in
Kick it Up's source code in mid-2011.