Explanation of KSF Pump It Up Step Format

by Turkeyslam

This article was originally written to aid Chris Danford and the Stepmania developers to better understand the KSF format, Kick It Up, and the way Pump It Up plays and works. It's highly technical, overly long, and was originally only intended to be written for that one purpose, but I decided to post it on the site for anyone who may be interested in it. Read on...

The KSF format, based off Pump grading from the original Korean Pump It Up mixes, is fairly simple. Unlike other step formats, it keeps everything at the most basic level, keeping flat 0s and 1s to indentify steps, while other factors get taken care of separately. Each KSF starts with mandatory headers, which can be put in any order, followed by a semicolon:

#TITLE:Artist - Song;
#BPM:120;
#TICKCOUNT:4;
#STARTTIME:5;
#STEP:

The first three are self-explanatory, really.

For the title, you can organize it as you please, and for Kick It Up, even if you put in a title with incorrect symbols for Korean characters (something like "Ăȶ«ëüµÍ"), it'll get rewritten in KIU to look Korean - even if those characters were for a different language.

For the BPM, you can go with whatever you want, but it's generally advised not to go DDR'y and have BPMs over 200 or so unless it's mandatory, because KIU grades like old-school Pump, where the judging is based off the proximity of where you hit the arrow, DISTANCE-WISE, not time-wise, on what it would look like on 1x (or any given speed). Since higher BPMs naturally pass faster, it technically makes a 200bpm song require 200% the accuracy of a 100bpm song to get a perfect, a 50BPM song only require 50% accuracy, and so on. This is why Pump grading is so different to DDR. For example, that step in Sakura where the BPM is incredibly slow, making the step incredibly difficult to hit - it's incredibly difficult not to get a PERFECT while in KIU, because grading is judged based off distance and nothing else. Old-school versions of Pump, all the way up to the early international Pump mixes, graded this way. Recent mixes may still factor this to some degree, but not as much. This is why it's a walk in the park to full perfect combo songs with very low BPMs.

Tick count, unlike DDR, is a flat, solid, unchangeable factor in a KSF, and is something which all formats of Pump steps (KSF, STF, NOT) abided by. Only the recent STX format has changed things, albeit still following in the strange method KIU uses (more on that later, with the BPM change section). Tick counts also affect the speed in which perfects get racked up during a hold. Technically, ANY tick count can be used, even worthless ticks like 5 and 7, but KIU has trouble properly registering anything that isn't one of the following: 1, 2, 3, 4, 6. A 1 tick count only supports 4th notes, that is, steps that are on the beat. 2 allows 8th notes, and 4 (the most common), supports 16ths. An 8 count does mean it supports 32nds, but KIU hates it and doesn't register steps properly at all. Also, anything above 8 will LOOK fine ingame, but won't play properly. The NOT format was similar, but you could get away with higher tick counts and still have the game playing it properly. A 6 tick count can be used without problems, allowing 24ths, but you will thus be stuck with this awkward tick count for the entire song, meaning you can't use traditional 16ths. Examples of songs in Pump which went the 6-tick route include Swing Baby (which used this tick HEAVILY) and Point Break. Musically, songs like this didn't require 16ths to go with the music, so something like this worked fine. The only way you could have both 16ths and 24ths (which won't play properly in KIU, by the way) is to do what Dignity did, using a tick count with the least common multiple of 4 (16ths) and 6 (24ths) - a tick count of 12. This made everything work. Theoretically you can take care of any song by just taking the least common multiple of all the tick counts the song needs and making that the tick count of the song. Anyway, let's go with a 4 tick count. A KSF like this will function where you can only place 4ths, 8ths, and 16ths, with other step variations being inaccessible. Holds are affected DIRECTLY by the tick count of the song (more on this later).

The #STARTTIME attribute is pretty much the same thing as in other games, and there is not much to explain here. You can go any way in Pump regarding where steps begin - the oldest Pump stepcharts always started with an early start time at the first solid beat of a 4/4 measure. Whenever the steps needed to begin, they begun. The reasoning behind this is that the animation of the little bar up top would only flash to the BPM of a song if the start time had already begun. Kind of irrelevant, but the precision of the tick count slightly differs in different places. KSF Creator, especially if you're recording steps as the song plays, are generally a good 5 to 7 milliseconds faster than what comfortably plays in KIU. Stepmania may go in a different directions. Most KSFs are designed to be precise to where it comfortably plays in KIU, so this needs to be kept in mind.

Following this is the last attribute, the only one of which MUST be the last one, #STEP. No semicolon follows it, and the steps begin IMMEDIATELY on the next line. The steps played are 0 if a step isn't present, and 1 if a step is present. It is organized in rows of thirteen numbers, with the first three being the five arrows on the player one side (bottom left, top left, center, top right, bottom right), the following five being for player two, and the last three being for the lightmap. All single player stepcharts must use the left side exclusively, with the right side being reserved for double mode charts, and "player 2" KSF charts. The light map digits do not matter whatsoever, and only are relevant when used on a Pump machine (where you'd have to use STF, NOT, or STX - not KSF anyway), and represent the lighting of each of three lights on the machine on the beat as it plays the stepchart along with the music. 99.9% of the time, this attribute is completely ignored, just leaving 0s. The only stepcharts where you'll find this are those converted from early STF and NOT charts of official Pump songs, mainly because KSF is directly related to those old Pump step formats.

Using the example of the 4 tick count, row 1 will be the first beat, row 5 will be the second beat, and so on. When the steps are finished, the ending of the KSF is represented by 2222222222222 as the last row. One thing about Pump is that the presence of these numbers represents the entirety of the playtime of the chart. There is zero opening time like in DDR/Stepmania for the arrows before the first step row begins, so this means if you have a 0 STARTTIME and you have a step on the first row, the millisecond the KSF begins, that step will already be passing. Likewise, when the 2222222222222 appears, the song ends, even if the MP3/WAV/music file is not finished. This is why it is heavily encouraged for KSF makers to add the rows of 0000000000000 silence after the steps end so that the song doesn't abruptly cut off. If the music file ends before the zeros end, then the KSF is forced to end.

The only stepcharts that have anything other than 0s, 1s, and 2s are charts with holds, and hold steps are represented with a 4. It doesn't work like in DDR where there are two numbers representing the beginning and end; only 4s are shown in a hold. This means that a single step with a 4 will be a hold step lasting one beat. It is common knowledge that Pump holds do NOT function the same way they do in other games, and the way it works is directly linked to the song's tick count. This is something that has never changed, and is still like this in the latest mixes. A hold is technically the exact same thing as a series of taps on the same step at the highest rate of the tick count. This means, the way perfects get racked up for a hold of two beats in a 4 tick count song will rack nine perfects, because it's the same as 9 taps on every 16th beat. The speed of the racking up of perfects will change according to tick count. An 8 tick count will rack them as 32nds, and this is why many songs in Pump It Up Zero rack up perfects at ludicrous rates. One thing about the holds is that there is no factor in when to let go, as long as there is a foot being pressed as the steps pass by. This means that even if you have the center step pressed 20 seconds before the hold occurs, if you don't let go, a center step hold passing by will rack every step of the hold as a perfect. Many players take advantage of this as a lazy way not to have to step on a step again to take care of the hold. So if there is a song with 10 steps in a row, a bottom left followed by a bottom right, each being holds lasting a full beat apiece, instead of stepping 10 times for each beat, just stand there depressing both steps, and everything will be registered as you hitting it all. The only discrepancy to this is if you do step offbeat for the first step, it won't always register as a perfect. Likewise, if you slightly let go during the middle of a hold and then restep, you might get a bad/good/great in there somewhere. And lastly, if you miss a single important hold, especially in a high tick count, you're screwed. You miss everything. Double, triple, etc holds have to have ALL steps depressed and hit properly for the hold to register. If you have a hold with three steps and only two are pressed, you're going to get misses for everything.

Steps in Pump are judged by whether you hit everything on a certain tick or not - NOT by your success in hitting a step. This means that a single step counts as one step, a double step counts as one step, and a triple step counts as one. Nothing changes even if it's a double mode chart and steps are hit on both sides simultaneously. It's all or nothing. If you miss any part of it, you get a miss for the whole thing.

There are a few more # attributes in the header that can be added, in any location other than the last one, but they are not mandatory. The first is #DIFFICULTY;, which assigns a level to the song, from 1 to 11. You can input a level over 11, all the way up to 99, but no matter what, in KIU it will show as 11, because this is the maximum. It was made this way because Pump at the time never had levels gong over 10. 11 is technically supposed to be representative of a "sub-10" chart. A second attribute is #PLAYER:DOUBLE;, which only has any use in Direct Move, another simulator like KIU. The only thing this does is tells that the stepchart is a double mode chart, because in Direct Move, KSF files can be named whatever the creator wants. This helps identify whether or not it is a two- player chart or a single-player double chart. KIU simplifies the process by only registering KSFs with the following titles (not case-sensitive):

Easy_1.ksf
Easy_2.ksf
Hard_1.ksf
Hard_2.ksf
Crazy_1.ksf
Crazy_2.ksf
Double.ksf
HalfDouble.ksf
CrazyDouble.ksf

The presence of one of these must be there or else the song won't even be shown as existing in the game. The titles are fairly self-explanatory, but will be explained anyway.

Easy, Hard, and Crazy, followed by _1, are the one-player charts for the single modes. Easy and Normal are the same thing, but it must be labelled as Easy_1.ksf to be played.

Double, HalfDouble, and CrazyDouble are the double charts, but not meant to be misinterpreted as steps of ranging difficulties. Double is just the usual one-player double charts, CrazyDouble is an alternative chart, usually used to represent Extra Expert Double charts from Extra mix or, most recently, Pump's Nightmare mode charts. HalfDouble.ksf is used only for the now obsolete mode of Half Double, where only the six center steps (of the ten) are used. In KIU, charts like these do not have the arrow bar for the top-left/bottom-left arrows on player one or the top-right/bottom-right arrows on player two. Any steps placed on those locations will be ignored if the chart is named HalfDouble.ksf (likewise, it's the same for single mode charts with steps on the other side). HalfDouble.ksf and CrazyDouble.ksf are only recognized on the later version of KIU, KIU Rebirth.

Steps labelled Easy_2.ksf, Hard_2.ksf, and Crazy_2.ksf aren't really used anymore, but used to be. In older mixes of Pump, all the way up to Extra/Perfect Collection and Premiere/Prex, on two player, many charts would be slightly altered to have the two sides playing independent, balanced steps based on the original stepchart. Sometimes the charts would be mirrored on the second side, and sometimes one side would stop while the other side continued, during a chorus of a song for example, while it exchanged with the other side the second time the chorus came around. These charts are not used anymore, but KIU still fully supports them. Some old-school Pump stepmakers still go ahead and include these charts anyway, to make the two player game a little more interesting. If a "_2.ksf" chart for a mode isn't present, the game will just copy over the player 1 steps for the other side. The game will NOT recognize the mode if there is a "_2" chart and not a "_1" one. Nowadays it's really unimportant and voluntary to use.

This essentially covers the basics of the format. The only thing left to discuss is the most complex aspect of the format: BPM changes. The method used for BPM changes in the format is EXTREMELY unorthodox, and may seem extremely confusing, but once you get the hang of it, it's actually pretty simple. Anyway, for starters you need to know the terms used to make these changes:

#STARTTIME2:512; and (optional, with two BPM changes) #STARTTIME3:3754;
#BUNKI:1420; and (optional, with two BPM changes) #BUNKI2:5607;

The first explanation, written by ROC Zombie from PH, explains how to use the BPM changes in a format where Stepmania will also understand the BPM change because the format technically still looks the same when being played on it. The second explanation is easier and simpler, but the end result may end up giving a stepchart that only KIU will understand and Stepmania won't whatsoever.

-------

"When creating songs with more than one BPM, it is necessary to put the steps in the correct format in order for Kick it Up to recognize the change. People will view this as “The BPM starts out slow, and then speeds up at a certain point”. However, KIU does this change much differently. Its method is “two different BPMs running simultaneously. When a certain point in the song is reached, the faster BPM then catches up, and becomes the current speed”. It might sound confusing, but it will be better explained here.

KSF step files can be compared to running a race. Since BPM #2 is moving faster it will therefore ‘catch up’ with BPM #1 and take over. This meeting point is called the Bunki.

Creating two separate step files is an easy way to make the final KSF. This is necessary in order to test the file and make sure the steps line up correctly with the beats. The first file contains ONLY BPM 1 and starttime 1 info. These are the normal speed / start time of a regular song. We will call this Easy_1.

Now we will create another step file and call it Hard_1. It will contain the second Bpm steps and start time. The start time value for our new file is the EXACT point in the song where this new speed begins. The value is in 1/100ths of seconds. You can use Goldwave to find this.

Looking at our Hard_1 file, we have steps that will begin at 196 BPM. After you have tested the steps, and both Easy_1 and Hard_1 steps line up correctly with the song, it’s time to combine the two together.

Open the Easy_1 file in the KSF editor. While it’s up, go to File and open your Hard_1 file. Take your mouse and highlight all of the steps in Hard_1 and click the Copy icon. Go to the Easy_1 file already open, and point to the area after your last step. Now click the Paste button and all of your steps are now listed on one file. The Start time that you had on Hard_1 will become the ‘Bunki’ value on our combined file. Make all the needed changes at this point. Fill in bpm 2 with what the second BPM is, and bunki with when the new BPM kicks in. Now it is time to calculate our start time 2.

Start time 2: A calculator is needed. Calculating the start time 2 value was NOT easy figure out! It took me a few weeks!

This start time is figured by measuring the ‘distance’ that will be traveled before it reaches its Bunki point (in this case, 24 panels). To figure your panel speed, divide 60 by your bpm2. (60 / 196 = .306) Now multiply that by the number of panels traveled (24) and add your start time 1 to this number and VIOLA, you have a VERY CLOSE APPROXIMATED Start time 2. [(.306 x 24) + 5.12 = 12.46]. After a little bit of testing and adjusting, I added 5/100ths to my final start time 2 to get 1252.

If you are working with 3 different BPMs, follow the same steps above, creating 3 separate files and then combining them after you test the steps. Starttime 3 is calculated the same way, and the panel speed is added to your start time 2 value instead of 1.

After enough experience, you will not need to make separate step files. Simply make all your steps at once if you like and then do the math with the panel speed for start time 2 and the bunki. The other method simply makes it easier to test your steps for accuracy before making the final file."

-------

Yes, that sounded confusing. And if you haven't figured it out yet, now there's an easier explanation. Note that using this will have the alternate BPM's steps possibly in another part of the KSF, thus rendering it useless in Stepmania.

Let's start with what's simple: Bunki. The Bunki value is quite simply when the new BPM comes in. However in KSF terms, it's not AS simple as that. The easiest way to explain it is that if you have two BPMs at once, the two BPMs are two STEPCHARTS playing simultaneously, and the bunki point is when it drops the first BPM's stepchart and goes to the next one. So create the chart as such.

Make the first BPM's steps and start time and so on be no different than how they are normally made. Once that's done, save it. Now find a new #STARTTIME value for the new BPM where if you play it, the steps will begin SEPARATED from the beginning BPM's steps. In other words, the second BPM will chase ahead of the first, and then "begin" at the #BUNKI point. This means that even if you timed everything right, it may "snap away" from the first BPM very noticeably because it's not following that BPM anymore. The best way to get it to work is to time it perfectly and then have a mirror of the first couple beats of the following BPM at the end of the steps of the first BPM. It'll create the illusion that ALL that is happening in the chart is it's speeding up at that point. This is how nearly all KIU BPM-change stepcharts work. The method ROC Zombie mentioned in his explanation is simple, but it just focused on making it where your #STARTTIME2 will be perfect and exact where there will be no gap between the BPMs, and at first glance the stepchart will look perfect because the stepchart is created where it perfectly swaps at the right point. To avoid ghost steps it's usually a good idea to put the #BUNKI a few hundredths of a second before the new steps kick in. To add a third BPM you follow the same procedure, where it'll be as if there's a THIRD "simultaneous stepchart". Three is KIU's limit, however.

The complexity of how to do this is what gets most people to avoid using BPM changes in KIU and with the KSF format at all. But it CAN be done, and examples of it can be found in some step projects at Pump Haven. As a matter of fact, this system for BPM changes is not unique to the format - it's an emulation of the EXACT thing done for Andamiro's old step formats from the old versions of the game. Thankfully, this is the only complicated aspect about the format, with everything being really, really simple. And that's about it, really.

Other notes regarding Pump steps include the following:

-Unlike in other games, every stepchart is completely independent of the others. Hard and Crazy mode, for example, can have different BPMs, titles, tick counts, and even different BPM changes. There is no syncing or matching with the two, even when two separate modes are played simultaneously by two players, such as in the Exceed SE and Zero arcade versions.

-Even though visually in programs like KSF Creator steps are organized in four-measure chunks for 4/4 songs, steps are recognized on a per-beat basis so 5/4 and 6/8 songs play identically to a 4/4 song.

-The KSF format was actually created by an employee at Andamiro even though it was never used in any arcade mixes. It is loosely based on Andamiro's original STF format, used in the first couple arcade games. The STF format used just 0s and 1s, and didn't have any kind of special modifiers. KSF added what it has, and NOT, which was used all the way up to Prex 1, is by all accounts technically just a KSF, with rows slightly scrambled up, and with encryption. Even the official (not homemade, but Andamiro-made) stepmaking program for arcade versions recognized KSF as one of the formats. This is why KSF is so widely regarded as being "the true Pump stepfile format" despite its heavy restrictions. The STX format used today in Prex 3 PC and later arcade mixes is essentially just a step further, just allowing tick count changes mid-song and more complex BPM changes within the song itself. Up until Exceed 2, these additional uses were hardly used at all, and mostly only things that can be done in KSF were used for the game's stepcharts.

That is about all there is to explain about the format. A copy of both versions of Kick It Up, the stand-alone easy -to-use KSF editing programs KSFEdit and KSFCreator, tutorials, and so on can be found here.