# StepMania Documentation

Revision 1.1x10^-8 (May 3rd, 2005)

(TOC is broken and outdated, scroll down)

# 1. What is StepMania?

StepMania is a music/rhythm game. The player presses different buttons in time to the music and to note patterns that scroll across the screen. Features 3D graphics, visualizations, support for gamepads/dance pads, a step recording mode, and more!
StepMania is capable of playing many game types. Currently, it supports games similar to Dance Dance Revolution, Pump It Up, EZ 2 Dancer, and Para Para Paradise. In the future, it will support games similar to BeatMania, Guitar Freaks, DrumMania, and more. The games played by StepMania are rhythm games. Notes scroll up from the bottom of the screen, and the player must hit the corresponding button on the controller in time to the. All games can be played using the keyboard, but the real fun comes when using specially designed controllers, like a dance pad or hand sensors.

# 2. System Requirements

For Windows:

- CPU: 400mhz or faster
- Graphics: OpenGL enabled DirectX 7 compatable graphics card (32MB of VRAM reccomended)
- Sound: A DirectX 7 compatable sound card
- Joystick: something that works (see http://www.stepmania.com/stepmania-old/adapter.php for details)
- Hard Drive: 10mb available for base, additional as required for songs.
- RAM: 128MB or higher

For Linux:

- CPU: 400mhz or faster
- Graphics: OpenGL enabled X11 compatable graphics card (32MB of VRAM or higher reccomended) NOTE: You MUST have working OpenGL libraries to run StepMania!)
- Sound: ALSA compatable sound card
- Hard drive: 10MB for base, additional for songs.
- RAM 128MB or higher
- Additional Libraries: madlibs, libvorbis, SDL, Xlib, liblua

For Mac:

[Someone want to help a man out here? I have never owned a Mac.]

# 3. Installation

## 3a. Installing StepMania from a binary

To install StepMania on Windows 98/ME/2000/XP:

1. Point your web browser to the StepMania Sourceforge.net project files page at http://sourceforge.net/project/showfiles.php?group_id=37892
2. Download the file stepmania-X.Y-Z.exe where X, Y, and Z are version numbers, and save it to your hard drive.
3. Double click Stepmania-X.Y-Z.exe, and follow the instructions on screen.
4. After installation, add songs, themes, noteskins, etc to their appropriate directories (see section 5)
5. To run StepMania, click the Start button, select Programs or All Programs, select StepMania (or Stepmania CVS) and click Play Stepmania.

To install on Linux/Unix:

1. Point your web browser to the StepMania Sourceforge.net project files page at http://sourceforge.net/project/showfiles.php?group_id=37892
2. Download stepmania-X.Y-Z-linux.tar.gz (where X.Y-Z are version numbers) to a folder on your hard drive.
3. Extract the archive using tar -zxvf stepmania-X.Y-Z-linux.tar.gz
4. Add songs/themes/noteskins/etc. to the appropriate folders (see Section 5)
5. To Start StepMania, run ./stepmania from the installation folder.

## 3b. Compiling StepMania from source

There are two methods of compiling StepMania. You can use the source tarballs provided for each release, or you may obtain fresh source directly from our CVS server. NOTE: To compile SM on Windows, you will need M$ Visual C++ 6 or higher.

### Source Tarballs

To compile/install StepMania from a source tarball on Windows:

1. Extract the source tarball using your preferred archiver into a locaton that you wish to build in.
2. Navigate to your source tree's src directory and double click on StepMania.vcproj. This will launch M$ VC++.
3. From the Build menu, select Build Solution (or Build StepMania, depending on version)

To compile/install StepMania from a source tarball on Linux/Unix

1. Point your web browser to the StepMania Sourceforge.net project files page at http://sourceforge.net/project/showfiles.php?group_id=37892
2. Download stepmania-X.Y-Z-linux-src.tar.gz to a location in your hard drive
3. Extract the archive using tar -zxvf stepmania-X.Y-Z-linux-src.tar.gz
4. In the extracted folder, type ./configure
5. Finally, type make (or gmake) to build StepMania

###

# 4. Using StepMania

Once you start Stepmania, you will be presented with the Stepmania Title Screen

Hit the Start or Back buttons (Enter or Esc by default) to go to the main menu. (Note that in Freeplay or Pay mode, the main menu is disabled)

## 4a. Starting the Game

From the Main Menu, select Game Start. After the warning screen appears, you will be presented with the Select Style screen.

Select one of the five styles to continue:

- Single: Standard 4 pannel mode for one player
- Versus: Standard 4 pannel mode for two players
- Couple: 4 pannel mode for two players with different steps for each player
- Double: One player plays on both pads simultaneously
- Solo: 6 pannel mode for one player

Once you select a style, you are presented with the Select Difficulty screen.

Select a difficulty to continue, or scroll right past Heavy to show the Challenge/Oni screen.

These modes are more difficult than the standard game modes.

Once you select a difficulty, you are presented with the song wheel.

Select a song with the Menu Left and Menu right keys (see Section 4c to define them)

Once you select a song, you are presented a variety of information about this song.

1. This is the currently selected song's banner.
2. This is the speed (in Beats Per Minute) of the currently selected song.
3. This is the Groove Radar. It shows how much Freeze, Chaos, Voltage, Air, and Stream a song has.
4. This is the feet rating. It shows how difficult overall a song is.
5. This is the song wheel. Rotate it to select a song with Menu Left and Menu Right, or Pad left and Pad right (see section 4c)
6. This shows how the songs on the song wheel are sorted. To change the sort press Up, down, up, and down on the pad or keyboard to display the list of choices for song sorting. Select one with Start.
7. This shows the current stage number. "Event" is displayed in Event mode.

To Start a song, select it, and press start. Depending on your options, you may also press start within a second or two after that to enter the Song Options menu.

## 4b. Song options

The song options menu contains a variety of options to alter the way the game is played. These include

- Speed: This setting defines the speed that the notes move at, relative to the song's tempo.
- Acceleration: These settings can make the speed of the notes change as they progress up the screen, making the game more difficult.
- Effect: These settings enabled a variety of effects on the notes, such as a "drunk" effect, making the game harder.
- Appearance: These options also affect the appearance of the notes, however these deal with their visibility.
- Turn: These options enable a turn in the notes as the move up the screen.
- Insert: These options insert random notes into the orignal step pattern.
- Scroll: These settings affect the placement of the stationary arrows.
- NoteSkins: Changes the noteskin.
- Holds: Enables or disables hold notes in some songs
- Mines: Enables mines in some songs, which when hit like regular notes, greatly decrease the player's lifebar.
- Hide Chooses how to hide the notes.
- Persp: Changes the perspeftive of the notes.
- Steps: Chooses the step set or difficulty to use.
- Character: Chooses from one of the installed dancing characters.
- LifeType: Chooses from two different types of life bars: the standard lifebar, or a "Battery" which allows only a set number of misses until the player fails, controled by BatLives.
- BarDrain: Affects how the bar drains when the player misses a note or hits a mine.
- BatLives: Sets the number of lives in Battery mode.
- Fail: Sets the type of fail. Immediate fails when the lifebar reaches zero, end of song waits until the end of the song to fail the player, and off disables fail.
- Assist Tick: Enables a metronome-like tick.
- Rate: Chages the rate the song is played.
- Save Scores: Enables the saving of scores to the high score table.

Once you press Exit on the second screen, the game will start.

## 4c. Game Options

Select Options from the main menu to get to the Options menu.

Below are descriptions of available SM options.

- Apperance options
  - Language: Sets StepMania's Language (english by default)
  - Announcer: Sets the announcer from a list of currently installed announcer packs.
  - Theme: Sets the theme from a list of currently installed themes.
  - Note Skin: Chooses the Note Skin from a list of installed note skins.
  - Instructions: Chooses wheter or not to show the Instructions screen explaining Hold notes.
  - Caution: Chooses whether or not to show the Caution screen after Game Start is selected.
  - Oni Score Display: chooses whether to display Oni mode Score in Dance points or Percent.
  - Song Group: Chooses whether to present a list of song groups, or select the All Music group by default.
  - Wheel Sections: This chooses whether to use Wheel sections (folders) in all song sort modes, ABC sort only, or never.
  - Course Sort: This changes the way courses are sorted.
  - Random At End: This chooses whether to put random courses at the end of the sort.
  - Translations: This shows whether to romanize some song titles.
  - Lyrics: This chooses whether to show song lyrics.
- Background options
  - Mode: This chooses the background animation mode (See section 5)
  - Brightness: This changes the brightness of the background animation
  - Danger: This enables/disables the Danger screen
  - Dancing Characters: This setting enables Dancing Characters (See section 5)
  - Beginner helper: This setting enables the beginning helper when Beginner difficulty is selected.
  - Random Backgrounds: This chooses the number of random backgrounds
- Bookkeeping: This displays the Bookkeeping screen
- Center Image: This option allows you to center the image on your monitor.
- Coin Options
  - Coin Mode
    - Home: This option mimics the home versions of DDR, enabling the main menu, and not requiring coins.
    - Freeplay: This mimics DDR arcade machines on Freeplay mode, disabling the main menu and not requiring coins.
    - Pay: This requires the coin button to be pressed before the game can be played.
  - Songs Per Play: Sets the number of songs the player gets per game.
  - Coins Per Credit: Sets the number of coins per credit
  - Joint Premium: Allows Versus and/or Doubles to cost the same as a one player game.
  - Event mode: Enables Event mode, allowing an unlimited number of stages.
- Config Key/Joy Mappings: Allows you to reconfigure the keyboard and joystick/gamepad/dancepad controls
- Input Options
  - Auto map on Joy change: Attempts to guess the configuration of the joypad when it is connected/inserted
  - Menu Buttons: Enables/disables dedicated menu navagation buttons similar to those on the DDR arcade machines.
  - AutoPlay: Enables Auto Play. Note that you can not get high scores while this is enabled.
  - Back Delayed: Chooses whether the back button has a delay or is instant.
  - Options Navigation: Chooses the style of options navigation
  - Wheel Speed: Changes the speed of rotation of the song wheel
  - Solo singles: Enables/disables Solo-style for 4 pannel mode (centers the notes)
  - Hidden Songs: If enabled, hides songs that normally are only accessable through Oni mode or the roulette wheel.
  - Easter Eggs: Enables "Toasty" for a combo of 1337 (and more..?)
  - Marvelous timing: Enables the Marvelous timing setting for all songs, or just courses
  - Allow Extra Stage: Enables an Extra Stage if the last song in the game is AA'd
  - Pick Extra Stage: Chooses whether the player picks the Extra Stage song
  - Unlock System (More info...TODO)
- Graphic Options
  - Display Mode: Chooses to display StepMania in a window or fullscreen
  - Display Resolution: Chooses form a list of possible resolutions
  - Color Depth: Changes the color depth between 16 and 32 bits
  - Texture resolution: Changes the maximum texture resolution
  - Texture color: changes the color depth for textures between 16 and 32 bit
  - Movie Color: Changes the color depth for movies between 16 and 32 bit
  - Smooth Lines: Enables drawing of the Groove Radar with antialiased lines
  - Cel-Shaded Models: Enables Cel-Shading on Dancing Characters
  - Texture memory: chooses whether or not to hold textures in memory
  - Refresh Rate: Overrides teh default refresh rate
  - Wait for VSync: Wait for the monitor's Vertical retrace before showing the next frame. Does not have an effect on framerate, but can reduce "tearing"
  - Show Stats: Shows Frams Per Second, Triangles per Frame, and Draws per Second in the upper right hand corner of the screen.
- Machine Options
  - Menu Timer: Enables/disables the timer on menus
  - Scoring Type: Chooses what scoring method to use
  - Judge Dificulty: Changes the timings for Perfect, Great, Good, etc
  - Life difficulty: defines the drain speed of the lifebar
  - Progressive Lifebar: Defines whether the lifebar is harsher on progressive boos/miisses
  - Progressive Stage Lifebar: Defines whether the lifebar is harsher in later stages
  - Progressive Nonstop lifebar: Defines whether the lifebar is harsher as a nonstop course progresses
  - Default Fail type: Sets the failt type; Immediate fails when all players have 0 life, Combo of 30 misses sets fail when both players have a combo of 30 misses, and End of Song stops the player at the end of the song.
  - Show Song Options: chooses whether to show the song options screen with song modifiers, note speed, etc
  - Name Entry: Shows the Name Entry screen
- Sound Options
  - Resampling Quality: Sets the resampling quality of sound
  - Attract sound frequency: Chooses how often to play the Attract sound, the sound that plays before a coin is inserted
  - Sound Volume
- Profile Options: Allows players to create profiles with controls and high scores
- Other Options
  - Autogen songs: Automatically generates steps from other gametypes (eg. makes dance steps to a pump song)
  - Autogen Courses: Makes automatically generated courses out of song folders and artist names
  - Fast Load: Does not check songs for changes
- Reload Songs/Courses: Checks/Reloads all songs/courses
- Test Input: Displays the Test Input screen

## 4d. The Stepmania Editor

TODO

# 5. Customizing StepMania

One of StepMania's most powerful features is the level to which the user can customize it. Everything from the user interface, to the sounds, and even the gameplay can all be edited and customized. Also, you can obtain add-on announcers, themes, dancing characters, and other goodies from around the net. See the Links section of www.stepmania.com for a start.

## 5a. Songs

Songs are obviously the most important part of StepMania. You can obtain songs from many places around the internet, some of which are described in the Links section of stepmania.com, or you can make your own.

### Adding Songs to StepMania

Songs are added to the Songs folder of your StepMania installation. All the songs a user has are broken down by groups. These could be the game that they were taken from, or by step author. The files are then broken down by the song that they go with. Each folder needs a step file (DWI or SM) and a music file (MP3/OGG). Optionally, lyrics, a banner and a background image can be included.

For example, Butterfly would be placed under songs\DDR 1st Mix\Butterfly\, and that folder would contain butterfly.dwi, buttefly.lrc, butterfly.mp3, butterfly-bg.jpg, and butterfly-banner.jpg.

### The .SM format

(Courtesy of [Who wrote the old manual anyway?])

The .SM song file format was created to be one file format that supports all game types that StepMania can play (dance, pump, beat, guitar, etc). The syntax of a .SM is similar to .DWI and .KSF except that some tags are different.
Note that StepMania can load images in PNG, GIF, PJG, and BMP formats, and can load sounds in OGG, MP3, and WAV formats.
Any text field in an SM file can contain UTF-8 characters.
#TITLE:...; - The "main title" of the song.
#SUBTITLE:...; - This text will appear underneath the main title of the song on the Select Music screen. e.g. "~Dirty Mix~" or "(remix)".
#ARTIST:...; - The artist of the song.
#TITLETRANSLIT:...; - Transliteration of song's main title.
#SUBTITLETRANSLIT:...; - Transliteration of song's subtitle.
#ARTISTTRANSLIT:...; - Transliteration of the artist's name.
#CREDIT:...; - Give yourself some credit here for creating a wonderful song.
#BANNER:...; - The file name of the banner image. e.g. "b4u-banner.png". This image must reside in the song folder.
#BACKGROUND:...; - The file name of the background image. e.g. "b4u-bg.png". This image must reside in the song folder.
#CDTITLE:...; - The file name of the spinning CD logo. e.g. "b4u-cdtitle.png". This image must reside in the song folder.
#MUSIC:...; - The file name of the music file. e.g. "b4u.mp3". This image must reside in the song folder.
#OFFSET:...; - The time in seconds at which beat 0 occurs in the music. This is specified as a floating point value. e.g. "2.34".
#SAMPLESTART:...; - The time in seconds to start the music sample that plays on the Select Music screen. This is specified as a floating point value. e.g. "32.34".
#SAMPLELENGTH:...; - The time in seconds let the sample music play after starting. This is specified as a floating point value. e.g. "16.00". Note that in the last 1 second of playing the music will fade out.
#SELECTABLE:...; - If "NO", the song can not be selected manually and can only be played as part of a course. If "ROULETTE", the song can can also be selected via roulette. The default value is "YES".
#BPMS:...; - A value of the format "beat=bpm". Indicates that at 'beat', the speed of the arrows will change to "bpm". Both of these values are specified as floating point values. You must specifiy a BPM value for beat 0. Multiple BPMs can be given by separating them with commas. e.g. "0=160,120=80".
#STOPS:...; - A value of the format "beat=sec". Indicates that at 'beat', the motion of the arrows should stop for "sec" seconds. Both of these values are specified as floating point values. Multiple stops can be given by separating them with commas. e.g. "60=2.23,80=1.12".
#BGCHANGE:...; - A value of the format "beat=bg name". Indicates that at 'beat', the background should begin playing a new background named 'bg name'. 'beat' is a fractional value value and 'bg name' is a string. Different bg changes are separated by commas. e.g. "60=falling,80=flower". When StepMania looks for a backgound, it searches in this order:

1. Looks for a movie with file name = "bg name" in the song folder. You must include the file extension in "bg name". e.g. "60=falling.avi,80=flower.mpg".
2. Looks for a BGAnimation folder with the name "bg name" in the song folder.
3. Looks for a movie with file name "bg name" in the RandomMovies folder. You must include the file extension in "bg name". e.g. "60=falling.avi,80=flower.mpg".
4. Looks for a BGAnimation with file name "bg name" in the BGAnimations folder.
5. Looks for a Visualization with the file name "bg name" in the Visualizations folder. For example, if you have a song B4U and special B4U-specific BGAnimations called "robot" and "electric". First, move the robot and electric BGAnimation folders into the B4U song folder (e.g. "Songs\4th Mix\B4U\robot" and "Songs\4th Mix\B4U\electric"). Then, using the editor, insert a new background change at each point in the song where you to switch to a new BGAnimation.

Each pattern of notes has the same basic format:
#NOTES:<NotesType>:<Description>:<DifficultyClass>:<DifficultyMeter>:<RadarValues>:<NoteData>;
NotesType: Must be one of the currently supported types in StepMania: "dance-single", "dance-double", "dance-couple", "dance-solo", "pump-single", "pump-double", "pump-couple", "ez2-single", "ez2-double", "ez2-real", "para-single"
Description: This will be displayed on the gameplay screen. This can be any text, but is most commonly:
"Beginner", "Basic", "Another", "Trick", "Standard", "SSR", "Maniac", "Heavy", "Challenge", "SManaic"
DifficultyClass: This value must be "beginner", "easy", "medium", "hard", or "challenge". These values correspond the levels of difficulty on the Select Difficulty screen.
DifficultyMeter: The difficulty of these notes as a bar rating. The value must be an integer between 1 and 10.
NoteData: This value requires a longer explanation.
Each note is represented by a character:
0 = no note here
1 = a regular "tap note"
2 = beginning of a "hold note"
3 = end of a "hold note"
a-z,A-z = tap notes reserved for game types that have sounds associated with notes
Notes that are hit at the same time are grouped into rows. For example, if the NotesType is "dance-single", the row "1001" would specify that both the Left and Right and Down panels should be hit at the same time.
The number of notes per row (also called the number of 'columns') depends on the "NotesType.
dance-single = 4 notes/row (Left,Down,Up,Right)
dance-double = 8 notes/row
dance-couple = 8 notes/row
dance-solo = 6 notes/row
pump-single = 5 notes/row
pump-double = 10 notes/row
pump-couple = 10 notes/row
ez2-single = 5 notes/row
ez2-double = 10 notes/row
ez2-real = 7 notes/row
para-single = 5 notes/row
Note rows are grouped into measures. The number of note rows you specify in a measure will determine the time value of each note. For example, if there are 4 note rows in a measure, each note will be treated as a quarter note. If there are 8 notes rows in a measure, each note will be treated as a eighth note. If there are 12 notes rows in a measure, each note will be treated as a triplet (1/12th) note. Measures are separated by a comma.
Example:
// measure 1
2010
0000
0100
0000
: // measure 2
0001
0100
0001
0000
3010
0000
0000
0000

### Backgrounds

StepMania supports three different modes of backgrounds. The default background mode can be set in the Graphic Options menu.
BGAnimations - Sprite animations similar to DDR 1st-5th Mix. There must be BGAnimation folders present in the BGAnimations directory, or else no background will be played. See the section called "BGAnimations Format" in this document for more information on the BGAnimations format. BGAnimations will perform better than the other background modes on slower computers.
Random Movies - The background will cycle randomly over any avi or mpg files in the "RandomMovies" folder in the StepMania program directory.
Visualizations - A random avi or mpg file will be chosen from the "Visualizations" folder in the StepMania program directory. This movie file will be played and blended over top of the song's background graphic.
Many video AVIs will require the DivX codec for playback. If you haven't yet downloaded DivX, you can get it from www.divx.com. Playing movies as the background is very processor intensive, and may cause choppiness on slower computers.
Sample animations, visualizations, and random movies can be found at www.stepmania.com.

### BGAnimation format

The BGAnimations folder in the StepMania program directory may contain several BGAnimation folders.
\BGAnimations\<anim folder>\<layer files>
<anim folder> is the name of the animation.
<layer files> are one or more graphics files that will be used as layers in the animation. Each sprite represents exactly one layer. Multiple layers can be specified by having multiple <layer files>. Layer files can be PNG, AVI, or MPEG files.
For example, a BGAnimation named "flower" may include the files:
BGAnimations\flower\1 TileScrollUp.png
BGAnimations\flower\2 StartOnRandomFrame ParticlesFloatDown 1x2.png
BGAnimations\flower\3 TileScrollLeft CycleColor 2x2.png
The layers of a BGAnimation are drawn from bottom in the order in which the layer graphics files appear alphanumerically. A layer file name will often begin with a number to control the order in which they are drawn.
Different "effects" are specified for each layer by adding tokens to the file name. Here are an explanation of the currently supported tokens:
UseSongBg - Use the song's background file instead of this graphics file. Since this graphics file is merely a placeholder, you might want to make this graphic a 1x1 graphic to save disk space.
Add - use additive blending instead of normal blending.
CycleColor - cycle the color of the layer over the colors of the rainbow
CycleAlpha - cycle the alpha channel of the layer over type
StartOnRandomFrame - Start the animation on a random frame. This is mainly useful for Tile or Particle effects.
DontAnimate - Stay on the first frame of this animation. This is only useful for layers with multiple frames.
(stretch effects) - These scretch the graphic across the extire screen.
ScretchScrollLeft,
StretchScrollRight,
StretchScrollUp,
StretchScrollDown,
- Scroll the layer in a direction
StretchWater,
StretchBubble,
StretchTwist,
StretchSpin,
- Deform the background sprite with an effect. Only stretch spin is currently implemented.
(particle effects) - Use the graphic to make individual particles on the screen.
ParticlesSpiralOut,
ParticlesSpiralIn,
- Spiral particles away from/toward the center of the screen.
ParticlesFloatUp,
ParticlesFloatDown,
ParticlesFloatLeft,
ParticlesFloatRight,
- Scroll the particles across the screen.
ParticlesBounce,
- Particles start traveling in random directions and bounce when they hit the edge of the screen.
(tile effects) - Tile the graphics across the screen, forming a grid of graphics.
TileStill,
TileScrollLeft,
TileScrollRight,
TileScrollUp,
TileScrollDown,
- Scroll the tiles
TileFlipX,
TileFlipY,
- Flip the tiles along the X or Y axis.
TilePulse,
- Tiles zoom in and out.

## 5b. Courses

CRS files define the courses used in the Nonstop, Oni, and Endless modes. All CRS files must reside in the "Courses" folder in the StepMania program folder. These rules determine which of the three modes a course will appear in:
Nonstop: Will appear if there is no #LIVES tag and #REPEAT is OFF.
Oni (Challenge): Will appear if there is a #LIVES tag and #REPEAT is OFF.
Endless: Will appear if #REPEAT is ON.
#COURSE:...; - name of the course
#LIVES:<0..10>; - An integer between 0 and 10. This line is optional.
#REPEAT:<YES|NO>; - start over after last stage?
#SONG: - can use any one of the following formats:
A fixed song:
#SONG:<group folder>/<song folder>:<difficulty>:<modifiers>;
example: #SONG:Nicolai Rimsky-Korsakov/Flight of the Bumblebee:BASIC;
example: #SONG:Oldies/Jump Jive and Wail:MANIAC:sudden,shuffle,reverse;
A random song:
#SONG:*:(<difficulty>|<meter range>):<modifiers>;
example: #SONG:*:MANIAC;
example: #SONG:*:8..10:1.5x,reverse;
A random song within a group:
#SONG:<group folder>/*:(<difficulty>|<meter range>):<modifiers>;
example: #SONG:Classical/*:3..6;
example: #SONG:Techno/*:MANIAC:1.5x,reverse;
A players best song:
#SONG:BEST<number>:(<difficulty>|<meter range>):<modifiers>;
example: #SONG:BEST1:TRICK;
example: #SONG:BEST4:MANIAC:1.5x,reverse;
A players worst song:
#SONG:WORST<number>:(<difficulty>|<meter range>):<modifiers>;
example: #SONG:WORST4:MANIAC;
example: #SONG:WORST1:TRICK:1.5x,reverse,drunk;
Descriptions:
group folder - The name of the folder that contains the song folder. (e.g. "Techno")
song folder - the name of the folder that contains files for the song. (e.g. "Flight of the Bumblebee")
difficulty - Can be one of the following: BEGINNER, EASY, MEDIUM, HARD, CHALLENGE.
meter range - A value in the format "x..y" where x is the lowest meter allowed and y is the highest meter allowed. For example, the string "7..9" would choose only from songs with a meter of 7, 8, or 9.
modifiers - A comma separated series of modifier strings. This value may be left blank. Any string you see on the Player Options screen is a modifier string. Some examples are:

0.5x, 0.75x, 1.5x, 2.0x, 3.0x, 4.0x, 5.0x, 8.0x
boost, wave, drunk, dizzy, space, mini
hidden, sudden, stealth, blink
mirror, left, right, shuffle, supershuffle
little, reverse, note, flat, plain
noholds, nofreeze, dark
0.7xmusic, 0.8xmusic, 0.9xmusic, 1.0xmusic, 1.1xmusic,
1.2xmusic, 1.3xmusic, 1.4xmusic, 1.5xmusic

## 5c. Announcers

Announcers folders must reside in the "Announcers" folder inside the StepMania program directory (e.g. "Announcers\James Earl Jones\"). An announcer folder contains several more folders - one for each announcer "trigger". Add as many .WAV, .MP3, or .OGG sounds as you want to the trigger folder. When StepMania wants to play a sound for that trigger, it will play a random sound file from your trigger folder.
Sound files in a trigger folder can have any name you want. It's recommended that you name the sound files according to what is being said (e.g. "everybodys waiting for you.mp3"). If there are 0 sound files in a trigger folder, or the trigger folder is missing, then no sound will be played for that trigger.
For a complete list of announcer trigger names, see the example announcer packs that are available at www.stepmania.com.

## 5d. Note Skins

Note skins allow you to customize the way notes appear. Note skins must reside in the folder "NoteSkins\<Game Name>\<Note Skin Name>". Note skins are specific to a particular game (dance, pump, etc). In the note skin folder, you must implement the folling files for each note:
<NoteName> receptor (3x1).png
<NoteName> tap note (NxN).png
<NoteName> tap explosion bright.png
<NoteName> tap explosion bright.png
<NoteName> hold explosion.png
<NoteName> down hold topcap active.png.png
<NoteName> down hold topcap inactive.png.png
<NoteName> down hold head active.png.png
<NoteName> down hold head inactive.png.png
<NoteName> down hold body active.png.png
<NoteName> down hold body inactive.png.png
<NoteName> down hold tail active.png.png
<NoteName> down hold tail inactive.png.png
<NoteName> down hold bottomcap active.png.png
<NoteName> down hold bottomcap inactive.png.png
<NoteName> tap.colors
"<NoteName>" must be the name of the note (e.g. "left", "upright", "snare"). Look at the example note skins included with StepMania for a complete list for each game.
Most of the note skin elements can use any number of frames. For example, the element "tap exposion bright" could have 4 frames (2x2), 2 frames (1x2), or just a single frame. The exception to this rule is "receptor", which must have 3 frames.

## 5d. Themes

All themes must reside in the Themes folder below the StepMania program directory. Inside a theme folder, you will all or only a few of the items below:
Themes\<ThemeName>\BGAnimations\
Themes\<ThemeName>\Fonts\
Themes\<ThemeName>\Graphics\
Themes\<ThemeName>\Numbers\
Themes\<ThemeName>\Sounds\
Themes\<ThemeName>\metrics.ini
The 5 possible folders in a theme hold "theme elements". A theme element is simply a little piece of the theme that can be changed. Each of the 5 folders contains different types of information as explained below:
BGAnimations: This folder contains BGAnimation elements for the different screens. Since all backgrounds for all the menus in the game are generated using BGAnimations, any screen in the game can have an animating background. Also, BGAnimations can contain movie layers. For more information about BGAnimations, see the section "BGAnimations Format" in this document.
Fonts: This folder contains graphics and font width data used by the font system. Font graphics and width files are generated using the program "Bitmap Font Builder", which is available at their site. To export a font for use in StepMania:
- In Bitmap Font Builder, choose Character Set->Full ASCII. StepMania can only load 16x16 character sheets.
- In Bitmap Font Builder, click File->Save 32bit TGA. Save the file some place that is easy to access.
- Open Photoshop and load the TGA file. Click the chanel "Alpha 1", then load this channel as a selection.
- Click back to the Layers tab and create a new layer.
- Choose Edit->Fill, and fill the selection with white.
- Delete the layer named "Background". You should now see a mostly transparent background with faint hints of white text.
- Click File->Save For Web. Choose the Format "PNG-24" and Save.
- Rename the PNG file you just saved to "<YourFontName> 16x16.png". (the "16x16" means that the graphic contains 16 * 16 frames worth of characters.
- Back in Bitmap Font Builder, click File->Save Font Widths (INI Format). Save this in the same directory where you saved the PNG. Rename the exported INI file to "<YourFontName> 16x16.ini" where the first part of the file name matches the PNG you exported.
- Done! The PNG and the INI file are your new font. Move them into your theme's Fonts folder.
StepMania will also look for the following optional lines in a font INI file:
CapitalsOnly=<0|1>: If 1, then StepMania will use the capital letter frames in place of the lower case letter frames. If not specified, StepMania will use 0 for this value.
DrawExtraPixelsLeft=<0..32>: If letters of your font are being chopped off on the left size, try increasing this value. If not specified, StepMania will use 0 for this value.
DrawExtraPixelsRight=<0..32>: If letters of your font are being chopped off on the right size, try increasing this value. If not specified, StepMania will use 0 for this value.
AddToAllWidths=<0..32>: If specified, this value will be added to the width of every character in the font. Increase this value if the width of all characters changes uniformly; for example, if you add a border to each character.
AdvanceExtraPixels=<0..32>: The value in this line determines the amount of space to advance between each character. This is usually small, as most fonts include spacing between characters in the body of the character. Increase this value to increase character spacing in your font. If not specified, StepMania will use 1 for this value.
ScaleAllWidthsBy=<0.0...2.0>: The width of every character in the font be multipled by this value. If not specified, StepMania will use 1 for this value.
LineSpacing=<0..64>: This controls the spacing in pixels between lines of text. This value is only used in text items that have multiple lines. If not specified, StepMania will use the height of the frames in your texture (which is 32 pixels for 512x512 graphics).
Top=<0..63>: This indicates the top of a typical capital letter, from the top of the frame. If not specified, this will be derived from LineSpacing.
Baseline=<0..63>: This indicates the baseline of the font, from the top of the frame. If not specified, the baseline is derived from LineSpacing.
Graphics: This folder contains graphics used in all of the screens. These graphics are the meat and potatoes of a theme. These graphics can be of any dimension. For example, your theme could have a "title menu logo dance.png" graphic that is 640x480 - which would take up the whole screen!
Numbers: This folder contains graphics used to render numbers. Every graphic in this folder must be 5 frames by 3 frames (5x3) and follow the standard layout (see the Numbers graphics in the theme named "default" for examples).
Sounds: This folder contains sounds. Sounds may be in OGG, MP3, or WAV format.
metrics.ini: A metric is simply values that can alter the appearance of the game. metrics.ini is a large list of values that will allow you to alter things like the position of elements in the menus, and the order of menu screens. There is no documentation or explaination of these values other than the value name. Because the theme "default" implements all possible theme elements and metrics, the metrics file "Themes\default\metrics.ini" contains a complete list of all possible metrics. DO NOT EDIT the file "Themes\default\metrics.ini". Instead, create a blank file "metrics.ini" in your theme folder, and override only those values you want to customize for your theme using default's metrics.ini to see what values are possible.
When StepMania looks to load a theme element from one of these folders, it will first look in the folder of the currently selected theme. If the element is not found in this folder, StepMania then look for the theme element in the theme folder called "default". The theme "default" is a base theme and guaranteed that a theme is usable even if it is missing elements.
This "fallback" system has other advantages too. User-created themes can override as many or as few theme elements as the author pleases. For example, you could create a theme called "MySuperTheme" which does nothing more than override the title menu logo. Here's how you would create this theme:
- Create a new folder in "Themes" called "MySuperTheme"
- Open the MyStepMania folder. Create a folder inside called "Graphics".
- Copy the file "Themes\default\Graphics\title menu logo dance.png" into your Graphics folder "Themes\MySuperTheme\Graphics".
- Edit your new title menu graphic to be whatever you want.
- Start StepMania, go to Appearance Options, and change your theme to "MySuperTheme".

### Actor commands

In the old paradigm, you would define the position of an Actor with two different metrics - one for the X position, and one for the Y. For example:
ObjectX=100
ObjectY=220
This system is being replaced by more powerful "commands strings". A command string can set positions, colors, effects, and also script animations over time. Positioning an Actor with command string would look like this:
ObjectOnCommand=x,100;y,220
A command string contains one or more commands separated by semicolons. This command string contains two commands: "x,100" and "y,220". A command is made up of a command name and a list of parameters. The command name and any parameters are separated by commas. In the example above, both the commands "x" and "y" both take exactly one parameter. Other commands like "diffuse" take 4 parameters (R, G, B, and A). For example, the command "diffuse,1,0,1,1" would turn an Actor's color to opaque purple.
Typically, the metrics file will have two commands per Actor - the "OnCommand" (which is where you command an Actor to tween onto the screen), and the "OffCommand" (for tweening the Actor off the screen).
Below is a list of actor commands and their C++ equivalents. I'll have an explanation of animations and more examples in the full documentation.
sleep BeginTweening( fParam(0), TWEEN_LINEAR );
linear BeginTweening( fParam(0), TWEEN_LINEAR );
accelerate BeginTweening( fParam(0), TWEEN_ACCELERATE );
decelerate BeginTweening( fParam(0), TWEEN_DECELERATE );
bouncebegin BeginTweening( fParam(0), TWEEN_BOUNCE_BEGIN );
bounceend BeginTweening( fParam(0), TWEEN_BOUNCE_END );
spring BeginTweening( fParam(0), TWEEN_SPRING );
stoptweening { StopTweening(); BeginTweening( 0.0001f, TWEEN_LINEAR ); }
x SetX( fParam(0) );
y SetY( fParam(0) );
xoffset SetX( GetX()+fParam(0) );
yoffset SetY( GetY()+fParam(0) );
zoom SetZoom( fParam(0) );
zoomx SetZoomY( fParam(0) );
zoomy SetZoomY( fParam(0) );
diffuse SetDiffuse( RageColor(fParam(0),fParam(1),fParam(2),fParam(3)) );
glow SetGlow( RageColor(fParam(0),fParam(1),fParam(2),fParam(3)) );
rotationx SetRotationX( fParam(0) );
rotationy SetRotationY( fParam(0) );
rotationz SetRotationZ( fParam(0) );
shadowlength SetShadowLength( fParam(0) );
horizalign SetHorizAlign( sParam(0) );
vertalign SetVertAlign( sParam(0) );
diffuseblink SetEffectDiffuseBlink();
diffuseshift SetEffectDiffuseShift();
glowblink SetEffectGlowBlink();
glowshift SetEffectGlowShift();
wag SetEffectWag();
bounce SetEffectBounce();
bob SetEffectBob();
spin SetEffectSpin();
vibrate SetEffectVibrate();
stopeffect SetEffectNone();
effectcolor1 SetEffectColor1( RageColor(fParam(0),fParam(1),fParam(2),fParam(3)) );
effectcolor2 SetEffectColor2( RageColor(fParam(0),fParam(1),fParam(2),fParam(3)) );
effectperiod SetEffectPeriod( fParam(0) );
effectmagnitude SetEffectMagnitude( RageVector3(fParam(0),fParam(1),fParam(2)) );
additiveblend EnableAdditiveBlend( iParam(0)!=0 );
Screen Select

ScreenSelect is a type of screen that presents the user with a list of choices. The choices shown on these screens can be Styles, Difficulties, PlayModes, or any combination thereof. Each ScreenSelect screen has two metrics that define what choices are shown (examples below). Currently, there are only two different screens that support the ScreenSelect framework.
- ScreenSelectMaxType1
- ScreenSelectMaxType2
- (more will be converted over in the next couple days)
// Example 1: Show all Styles for the current game type the DDR MAX Select Style template
[ScreenSelectMaxType1]
ChoicesType=0 // 0=styles, 1=difficulties, 2=modes, 3=games
Choices=
// Example 2: Show specific Difficulty and PlayMode choices using a DDR MAX Select Difficulty template
[ScreenSelectMaxType2]
ChoicesType=1 // 0=styles, 1=difficulties, 2=modes, 3=games
Choices=Beginner,Easy,Medium,Hard,Nonstop,Oni,Endless
// Example 3: Show specific Style-PlayMode-Difficulty combinations using a DDR MAX Select Style template
ChoicesType=2 // 0=styles, 1=difficulties, 2=modes, 3=games
Choices=versus-arcade-medium,couple-arcade-medium,double-arcade-medium,single-arcade-medium,single-battle-medium,double-battle-medium,couple-battle-medium,versus-battle-medium
5e. A note on how SM loads textures

* What are textures?
"Texture" is simply another name for graphics file. The name "texture" is more common when taking about 3D graphics. This document uses "texture" and "graphic" interchangeably.
* How to you specify that a texture has multiple frames (for animation)?
Simply add the string "(NxN)". Immediately before the "." that separates the main file name and the extension. For example, suppose there is a file called "title menu logo.png" that you would like to turn into an animation. Now, you create an graphic file with 9 frames of animation - 3 frames wide and 3 frames high. Name this file, "title menu logo 3x3.png", and StepMania will play the graphic as an animation with frames in the order left-to-right, top-to-bottom, with 0.20 seconds separating each frame.
* What are .sprite files?
.sprite files are a way to have even more precise control over how your graphics animate. Each sprite has multiple "states". For each state, you may specify: 1) What frame of the graphic to show, and 2) how long to show this state before moving to the next state.
Let's look at an example .sprite file:
[Sprite]
Texture=dancer p1 1x3.png
Frame0000=0
Delay0000=0.05
Frame0001=1
Delay0001=0.05
Frame0002=2
Delay0002=0.05
Texture is the name of the texture file to use. This must reside in the same directory as the .sprite file. If your texture has multiple frames, be sure to specify the dimensions in the file name using the convention described above.
FrameNNNN is the index of the frame number to use for the first state of the animation. Frame may range between 0 and (total number of frames - 1). Frame indicies move left-to-right, top-to-bottom over the frames in an image.
DelayNNNN is the time in seconds to show the state.
* My graphics show ugly banding or look washed out. What can I do?
Change your PNG images to use "palette mode" instead of "RGB mode". Paletted images have three advantages:
- StepMania can load paletted images with higher color precision than RGB images.
- paletted images use much less texture memory than RGB images.
- paletted images often have a smaller file size than an equivalent RGB mode image.
However, paletted PNGs have a couple limitations:
- they support you to only "on/off" alpha.
- they support a maximum of 256 colors. This can make smooth gradients look ugly.
Alternatively, inserting "dither" into filenames will instruct StepMania to dither the image when loading.
* Why do the graphics look so blurry?
Some 3D graphics cards (the Voodoo3 in particular) do not support textures greater in size than 256x256. If a texture is larger than the card's maximum texture size, the image will scaled down internally resulting in output that looks blurry.

# 6. Supported Controllers or Controller Adapters

For a list of controllers and conroller adapters supported by StepMania, see http://www.stepmania.com/stepmania-old/adapter.php7. SMConvert

Comming soon!

# 7. Getting Help/Contact

There are a variety of ways to get help with StepMania. If you have thoroughly read this manual (emphasis on thoroughly), and still require help, you can either:

- Use the IRC chat room, located on irc.faereal.net port 6667 channel #stepmania. This is NOT (I repeat, NOT) a file server channel and no file servers are allowed!
- Use the mailing lists, available from the Mailing Lists Page.
- If your problem is a bug in the program, report it to the Bug Tracker.
- You can also post on the new Stepmania message boards, which can be found here

# 8. Changelog

May-3-2005 Added tons of stuff from the old manual, TOC broken.

May-1-2005: Initial Rewrite.

# 6. Supported Controllers or Controller Adapters

For a list of controllers and

# 7. Getting Help/Contact

There are a variety of ways to get help with StepMania. If you have thoroughly read this manual (emphasis on thoroughly), and still require help, you can either:

- Use the IRC chat room, located on irc.faereal.net port 6667 channel #stepmania. This is NOT (I repeat, NOT) a file server channel and no file servers are allowed!
- Use the mailing lists, available from the Mailing Lists Page.
- If your problem is a bug in the program, report it to the Bug Tracker.
- You can also post on the new Stepmania message boards, which can be found here

# 8. Changelog

May-1-2005: Initial Rewrite.