Site Menu
where do you wanna go?

Translate PH to your language!

Media DB

PH :: Google AdSense
supported links

Media DB Navbar
all the site content we have to offer!

Game Version MP3s - GSTs
Remixes/Full Songs - GSTs
Full Version Songs - OSTs
Pump Simfile Bumper Packs
NX Gameplay Videos
PumpStreet Video Collection
Music Videos
Background Animations
O2Jam Keyboard Challenge
Custom Remixes
Miscellaneous Videos
Miscellaneous Music
Simulators/Simfile Utilities
Other Files

Stepmaker pages:
Funbox :: Hozz
Koop :: Morrigan
Mr. Scar :: NVK
ocfernan :: ROC Zombie
valius :: Others

PH Members - please enter the download center for additional hidden download categories and files.

If you are a newly registered member and would like to have access to additional download content, click here to send an allowance request for Pump Haven Step Points.

Pump Haven :: The KSF Guide For Dummies: Redux!
4:48PM CST :: 7/05/06

The KSF Guide For Dummies: Redux!

by Wolfman


This guide will attempt to document everything required to convert KSF files to SM files without a problem...and maybe even write KSF files out as well (as a followup to Turkeyslam's guide, put into a different perspective).

KSF files are the simfiles used in PIU simulators.  The two major simulators players turn to are Kick It Up (KIU) and Direct Move (DM).  They behave similarly in most regards except for Tickcounts and BPM changes, which will be documented later.  Unless otherwise said, assume that this guide is for those that have KIU-compliant files.

KSF files are designed to be minimalistic.  Each file contains required headers, occasionally some optional headers, and the steps for _one_ difficulty.  The headers are defined below, along with a basic example:

#TITLE:Banya - Love is a Danger Zone [Crazy];

SM's #ARTIST and #TITLE tags are combined into one: there is no concept of #SUBTITLE.  The only thing required is the song name; Artist and difficulty is optional, but recommended whenever possible.


BPM is simply the BPM of the music.  This is relatively self explanitory, and a required tag.


The difficulty is an optional parameter.  It's used to rate how hard the song is.  In KIU, it can only go up to 11; I'm unsure if DM has this restriction.


The tick count, another required tag, defines the types of notes allowed for the duration of the song.  1 allows only quarter notes; 2 4ths and 8ths; 3 4ths and 12ths; 4 4ths, 8ths, and 16ths; 6 4ths, 8ths, and 12ths.  Other tickcounts are allowed, but going beyond these does not work in KIU.  DM can change the tick count midsong; this is to be documented later.  Also of interest: the tick count directly affects how holds are affected (again, more later).


It's not exactly the gap, but the purpose is the same.  The music starts up right away upon getting past the full screen title card.  The start time, which is measured in centiseconds, defines how long to wait before the steps start.  If the steps start late, decrease the start time, and vice~versa.  Note that with most KSFs, the start time is designed to be worked with PIU simulators, not Stepmania; manual adjusting might be required.


Nothing follows to the right of the Step tag.  Immediately below that, though, the steps begin.  The step notation will be described shortly.

No more headers can be placed after #STEP (DM exceptions, see later).

The Step Format:

The tick count defines how many rows per measure.  As said before, a tick count of 1 only allows quarter notes, and thus you get 4 * 1 rows in one measure.  Most songs use a tick count of 4, or 16 rows per measure.

Each row has exactly 13 numbers in it.  The first five are always in play: they represent the 5 arrows on the left side of the PIU pad in order of down-left, up-left, center, up-right, and downright.  The next 5 numbers are used either in double or couple modes of play: they are ignored otherwise.  The last three deal with the lighting system in the arcades: it's alright to leave these alone.

The only numbers used in these rows are 0, 1, 2, and 4.  0 is nothing, and 1 is a tap.  A row of 2s signifies the end of the step file, and the music cuts off.  A column of 4s is a PIU hold note.

Hold notes in PIU have the following behavior.  The first 4 is the equivalent of the head. The remaining 4s form the rest of the hold.  As soon as the last 4 is passed, the hold ends.  A judgement is given when you step on the first 4, and then while you are holding the hold, a judgement and combo increase is given for every 4 you successfully hold.  Letting go starts a chain of misses for each 4 passed up until you get on it again.  The tick count comes into play here: the higher the tick count, the more judgements accumulate quickly.  This means holding onto a hold with a high tick count can regain life quickly, while not being on it can suck it dry just as fast.  

Currently in SM, the only types of holds available are the traditional DDR style holds, and the ITG rolls which are DDR holds that must continuously be activated.  A new notetype can be added to allow the possibility of PIU style holds: that is a topic for another day however.

For the most part, this information is enough to get most people started on PIU simming, and for SM converting.  Unfortunately, this doesn't cover the concept of BPM changes.  First, some general information would be of use.  There are two ways to do so, depending on which simulator one wishes to use the ksfs on.  Regardless of how it's done, all BPM information is stored within the individual KSF file itself!  This means one chart for a song can have no changes, while a second one could put in a slow down or speed up if wanted.  PIU Exceed Home Version and PIU Zero Arcade take advantage of this by allowing two people to play the same song and have different BPM effects.  A famous example would be the song Phantom: on Normal and Hard, the song stays consistent the whole way; on Crazy, there is a slowdown about 1/4 of the way in that can be disorienting to those that play on high speed mods; on Nightmare, different parts of the song basically get "jittery" during the game.  Since SM ties BPM syncing to the whole song and not the individual difficulty, however, this presents a problem for those that would play 2 KSFs (or 2 of any other sim file that relies on this method) that aren't the same "sync".  One chart would appear, but the other one wouldn't.  It is mostly this behavior that needs addressing.

KIU's method of changing BPMs will be discussed first; then DM.


KIU simulates the older versions of Pump in terms of how to handle BPM changes, mostly Premiere 1 and below.  It relies on what is called #BUNKI.  In simple terms, #BUNKI is the exact centisecond where the song changes the BPM.

To change BPMs, extra tags are required in the header.


BPM2 is what the second BPM change will be.


BUNKI is the centisecond that BPM2 activates.  To easily find the Bunki, use either an MP3 analysis tool like Goldwave or Audacity to find the exact centisecond you want the chart to activate BPM2.


STARTTIME2 is something that really seems unnecessary, but is required for reasons only Andamiro knows (an employee of theirs actually wrote the original KSF format).

Instead of boring you guys with the technical information on how there can be other start times, I'll just show the formula required to get the proper STARTTIME2.  Assuming proper tags:


There are limitations, unfortunately.  If STARTTIME2 ends up negative, then the change won't be recognized by KSF, and thus it can't be used.  If you want another BPM change, just use BPM3, BUNKI2, and STARTTIME3 for the 2nd change, but going beyond that is illegal.  Also, BPM stops, where the whole scrolling just stops (thing era, Healing Vision Angelic, or just about any Max song in DDR terms), is not possible.

For the most part, that is the simple way of how to handle BPM changes under KIU.


DM was an attempt to give the KSF format more flexibility, such as changing tick counts mid-song and a different way of doing BPM changes.  After Andamiro started using the STX format for Prex 3 and beyond, DM eventually replicated most of the STX functions (including changing tick counts and simpler BPM changes) in version 5.0.

Instead of defining everything at the header, the changes go right behind the notes that activate the change itself!

Changing the tick count is done in one of two ways from I've seem.  The first way is the same way as the header does it: #TICKCOUNT:#; does the trick.  The second way is to use a bracket system: |T#| is used to change the tick to the requested number.  Changing the BPM is done in the following format: |B###|, where ### is the BPM.  Both the BPM and tick count can be changed at the same time.  More than 2 changes of each kind can take place, which means that if one wanted to do a KSF of the original Healing Vision from DDR, one could do so and not be limited to only 2 changes at max that might not even work.  Stops can be implemented with |D####|, where the number must be given in milliseconds (why milliseconds when the rest is in centi?).

For those wondering how files are named in the KSF system, I will explain it now.  All song files must be called song.mp3.  To have a demo loop, intro.mp3 is used.  I'm unsure how to translate that directly to SM's demo tag.  A Disc.bmp image is used as the image for selecting a song, simulating the banner.  Title.png (or Title.bmp), which is normally used as a title card in between choosing the song and playing the song, can be used as the background if no movies are present.  Movies are done with Song.mpg (it requires KIU Long Notes, a special version of KIU) ,and the movie is NOT sent back to the background upon the last step.

The step files are limited to the following: Stepmania/DDR "equivalents" as suggested by AJ are listed alongside.

Easy_1.ksf - single light
Easy_2.ksf - couple light
Hard_1.ksf - single standard
Hard_2.ksf - couple standard
Crazy_1.ksf - single heavy
Crazy_2.ksf - couple heavy
Double.ksf - double standard
CrazyDouble.ksf - double heavy
HalfDouble.ksf - no real equivalent; double light if required

That is basically all one needs to know about converting KSF to SM and back again.