# `pydance` User's Manual

# About `pydance`

Have you ever gone to an arcade and seen some crazy girl busting moves on some sort of metal panel of sorts, or a guy making a fool of himself trying to dance without watching the screen? Well, that game is probably Dance Dance Revolution, or DDR for short, which has been a hit in Asian countries for awhile and is finally getting popular in Europe and North America. It might also have been a similar game, such as Pump It Up, or EZ2 Dancer.

`pydance` lets you play these games, and others like them, on your computer, either with the keyboard or with a custom controller. What you do is watch the screen as colored arrows move up the screen. As soon as they cover up stationary arrows at the top, you step (or press) the corresponding direction, in time with the beat of the music.

This manual is designed to guide you through the process of getting and installing `pydance`, finding songs, setting it up, and dancing the night away. In addition, it has instructions for making your own dance patterns or arrow graphics.

You don't need a dance mat to play `pydance`! It's a lot more fun if you do, but you can also use your keyboard or gamepad.

## System Requirements

These are rough guidelines. Depending on your graphical theme, operating system, and so on, these requirements can differ. Although it is possible to install and play `pydance` on systems slower than this, the frame rate (and input latency) will be high enough that it won't be much fun.

Operating System
  GNU/Linux (Debian is the easiest to use with `pydance`), Mac OS X, or Windows 2000 or higher. If Windows is your OS of choice, we can't help you debug. If Mac OS X is your OS of choice, we'll have plenty of trouble as well, but it's likely to work in the end.
Video Card
  A video card capable of doing 640x480x16bpp, which is most video cards made since 1995. More recent cards will be faster, but many old cards (ATI Radeon 7000, Matrox G200, nVidia TNT1) will be able to run `pydance` acceptably.
Processor
  We recommend a 1 GHz IA32 or 600 MHz PPC processor, or better, for `pydance`. However, `pydance` will run acceptably on a P3-500 or equivalent.
RAM
  At least 64MB is required. 128MB is very strongly recommended. `pydance` uses RAM to cache graphics, so more RAM means the UI will respond faster.
Hard Disk Space
  `pydance` requires about 5MB (around 50MB if you don't already have Python, SDL, or Pygame installed) of hard drive space to install. Songs take 1MB to 6MB each, on average. If your RAM is low, you will also need hard drive space for swap.

## What `pydance` Can't Do

Upfront: This program is not perfect. There are some things it can't do, either because we haven't gotten around to making it do them yet, or because we don't want to. On the whole, these are very minor things, but they're faults nonetheless.

Play MP3s
  `pydance` has very poor MP3 support. Some MP3s will load; most won't. Many will load, but then later cause `pydance` to crash, even if you aren't using them for anything. Setting your Preview mode to "Safe" can alleviate some of the problems, but not all. `pydance` is capable of loading Ogg Vorbis (.ogg) and Wave (.wav) files without issue, however.
Display Most Background Movies
  Many dancing games have movies playing in the background. `pydance` cannot load these movies.
"Magic Dance" or "Challenge Mode" games
  "Magic Dance" was a rare DDR mode that appeared in DDR Disney Rave. "Challenge Mode" appeared in DDR 4th mix and Ultramix (for the X-Box). Neither of these modes is supported (nor are they very popular).
"Half Double" games
  "Half double" is a mode in Pump It Up that uses a different part of each mat. `pydance` can emulate half double by playing regular doubles mode, and having steps only appear on the relevant panels.
Sundry Proprietary Konamiisms
  `pydance` cannot read your Playstation memory cards, nor can it register you for Internet Ranking scores.
Be a DDR/PIU/EZ2/etc. Arcade Machine
  We're not aiming to perfectly clone the arcade games with `pydance`; to start with, since we support at least 5 different arcade machines, that's impossible. We have our own interface, scoring system, and other ideas about what makes a fun dancing game. (Technically, if you put a computer running `pydance` inside an arcade cabinet and attached some pads and a keyboard, I guess it would be an arcade machine; but it still won't look like the other games very much.)
Network Play
  Although a future version of `pydance` might have network support, the current version does not. The best way to ensure that `pydance` does have network support in the future is to help write it yourself.
Edit Dance Patterns Graphically
  There is no graphical step pattern editor for `pydance`'s .dance format; instead, you can use a text editor.

# Installing `pydance`

Throughout the install guide, two path "aliases" will be used. `pydance_path` refers to the place you're running pydance from (e.g. `/usr/share/games/pydance/`, `/home/myuser/pydance/`, or `C:\games\pydance\`). `rc_path` refers to a "user-specific" path. On Unix, this is `~/.pydance/`. On Mac OS X, this is `~/Library/Preferences/pydance/`. On Windows, this is the same as the place you unpacked `pydance`.

This guide always uses '/' to separate directories. Windows users can also use '\' which they might be more accustomed to.

## Getting Python and Pygame

`pydance` is written in the Python programming language, and uses the Pygame game programming library. While this makes the program small and easy to develop, it also results in a few more things to download.

More detailed (and/or recent) instructions for installing Python and Pygame are available at the `pydance` download page.

### Unix

You will need Python 2.4, and Pygame 1.8.1. The `pydance` download page contains links and information on how to get the packages you need. Usually, these will be easy to find, or may even already be installed.

### Mac OS X

You want the Pygame kitchen sink install, which contains everything you'll need.

### Windows

Download a recent version of Python 2.4, and Pygame 1.8.1.

## Getting `pydance`

To get the latest version of `pydance`, visit the `pydance` download page. It is available as a .zip or a .tar.gz file. The site also contains information about installing from packages for Debian, Mandrake, and Gentoo GNU/Linux, and also has a disk image for Mac OS X users.

Otherwise, to run `pydance`, you can often just download the source, unpack it, and double click on `pydance.py` (or run `./pydance.py`). The `INSTALL` file included with `pydance` has detailed installation instructions for Unix.

## Getting Songs

`pydance` requires songs to run properly. There are some free songs available on the `pydance` site, one of which is a "how to play" tutorial. In addition, there are many other songs available on the web.

All song files must go in one of your song directories, `rc_path/songs/` and `pydance_path/songs/` (when you run `pydance` from a terminal or command prompt, it will print a list of the directories it's searching for songs).

### Installing .dance Files

The .dance format is `pydance`'s native step file format. .dance files are accompanied by a music file (.ogg), and optionally a banner, background, and CD title (all images). Assuming the .dance file is properly constructed, you can simply put the .dance, .ogg, and other files anywhere inside one of your song directories (however, they should be in the same subdirectory).

### .sm and .dwi Files

.sm and .dwi files are file formats used by other popular PC dancing games. These require a little more structure than .dance files; they must go in `songdir/Mix Name/Song Name/`, where "Mix Name" is the name of the folder you want the song to be in "Sort by Mix" mode, and "Song Name" is the name of the song itself. Like .dance, .dwi and .sm are accompanied by music and image files, but unlike .dance, you cannot put multiple .dwi or .sm files in the same directory; you must put them in separate subdirectories according to mix and song name.

You might also run across a few ".smzip" files. These are ordinary zip files which you can open with any unzipping utility.

### .ksf Files

.ksf files are yet another popular file format. Patterns in .ksf format will come as multiple .ksf files, one or two audio files, and zero to two image files. Like .dwi or .sm files, each song needs its own directory, which contains all the .ksf, audio, and image files for that song.

Some .ksf files might also need to have that directory named in the format `Artist Name - Song Name/`.

## Setting Up a Mat

`pydance` supports anything that looks like a joystick (or gamepad) or keyboard to your operating system. This includes most mats and adapters. However, some adapters map (e.g.) left and right onto a single joystick axis, which means you can't press left and right at the same time. This doesn't affect most games, but will affect `pydance`.

### Attaching a PSX/PS2 Mat

The most popular dance mats are for Playstations or Playstation 2s. The best adapter for these is an EMSUSB2, which lets you connect two mats to a USB port. The EMSUSB2 works in Linux, Mac OS X, and Windows, and any OS that supports standard USB joysticks. You can also purchase dance mats themselves at Level Six. If you live outside of North America, buying an EMSUSB2 from Lik-Sang might be easier, because they can ship from Europe and Hong Kong as well. If you're looking for a high-quality dance pad, Cobalt Flux pads sells metal pads for $300. They have all 9 panels (center and the 8 directions), and work with `pydance` if you have a PS2-to-USB adapter like the EMSUSB2.

Some other adapters are also supported. The parallel port adapter that comes with Buy'n'Shop DDR mats is supported on many platforms, including Linux with the use of our ddrmat.o kernel module. However, the EMSUSB2 is the most recommended.

The Radio Shack adapter will not work with `pydance`. Don't buy it.

### Attaching a Pump It Up Mat

Pump It Up mats come in two varieties, PS/2 and USB. The PS/2 variety is just a keyboard, that uses QESZC or 79513, and Escape. It is supported immediately on any platform (but remember to map it with the keyboard, and not joystick, controls). The USB variety is also a keyboard, but doesn't inform the OS that it is such. On Windows there are drivers to enable it (that come with the mat). On Linux, you can use a USB to PS/2 adapter.

### ParaParaParadise Controllers

Although the PPP controller appears as a USB joystick in all operating systems, it does not send any events when a sensor is triggered. So it will not work with `pydance`, under any OS.

### Other Mats

There exist some other mats, such as the X-Box DDR mat, and some mats that hook directly up to a parallel or USB port. If your OS detects these as a joystick or keyboard, and they use buttons (or axes and buttons) to record direction presses, `pydance` will support them. If you are buying a mat and adapter for the first time, though, we recommend avoiding these and going to the kinds that will definitely work.

This is all you need to start playing `pydance`, a few songs and a mat. If you're starting out you can skip the next few sections, because those files are optional.

## Getting Courses

`pydance` comes with some courses for "Nonstop Mode" (explained later), but you can also download your own. Courses go in `rc_path/courses/` or `pydance_path/courses`.

### .crs Files

`.crs` files are the only courses supported by `pydance` currently. These are used with `.dwi` files, usually. Like those, they need to be in a subdirectory `coursedir/Mix Name/Course Name/`. If a file exists with the same name as the .crs file but ending in .png, (e.g. `POP 8.crs` and `POP 8.png`), then that image will be used on the course selection screen.

Also, if there exists a file `coursedir/Mix Name.png`, it will be displayed for that mix folder in the course selector.

## Getting CD Titles and Banners

The song selector lets you have banners for different folders. These go under `pydance_or_rc_path/banners/sorttype/foldername.png`. For example, if you want a banner for your "DDR 4th Mix" folder, you can name it `~/.pydance/banners/mix/DDR 4th Mix.png`. If you want one for the "Title: A" folder, use `~/.pydance/banners/title/a.png`.

`pydance` also supports "CD titles", which are small images that appear next to the song in the song selector, usually indicate what album or game it is originally from. These go under `pydance_or_rc_path/cdtitles/`, or in the same directory as the song file itself.

## Graphical Themes

There are many different arrow graphics that come with `pydance`, and you can also add more. These go under `rc_path/themes/gfx/NxN/themename/` or `rc_path/themes/gfx/NxN/themename.zip` (the .zip file can be read without being unpacked). N is the height and width of the images in the theme; different game modes use different image sizes.

## Announcer (DJ) Themes

`pydance` supports an announcer, who talks during the game, giving you feedback on your progress. You should unzip (or untar) such themes in `rc_path/themes/dj`, into a subdirectory of their name. Announcers are still being developed, and don't work very well.

## Font Themes

`pydance` user interface can be customized to use True Type fonts different from the default Pygame font. Currently, VL PGothic Font is supported to display song titles and locales with Asian characters. Font theme configuration files and font files are found under `rc_path/themes/font` with a configuration file for each theme, describing what font and size combination should be used for each UI element.

# Playing the Game

A dancing pad normally has somewhere between 6 and 11 buttons. These buttons are used to control the `pydance` interface, as well as play the game. When using them to navigate menus and so on, they have slightly different names.

Up, Down, Left, Right, Start, Select
  These are still the same. Start usually activates menu (the same as Confirm), but sometimes does other things.
Up Right, Center
  These are called "Confirm", and activate menu items.
Up Left
  This is "Cancel", and backs out of menus or folders.
Down Left and Down Right
  These are Page Up and Page down, respectively.

Each player can have one keyboard key and one joystick button assigned to each direction. In addition, some keys are automatically assigned to a direction or action, if they aren't mapped to something else.

F11, f
  Toggles fullscreen or windowed display, under Unix. This can't be used in the middle of a song.
Backspace, s
  Change the sort order in a menu.
Print Screen (or SysRq)
  Take a screenshot.
Main arrow keys
  Up, down, left, and right.
Escape, Insert
  Cancel.
Tab
  Select.
Return
  Confirm.

## The Main Menu

If your songs are properly installed, this is the first screen you will see after `pydance` finishes loading (if your songs aren't installed, you'll get a reminder to install them).

Up or Down
  Select an item in the menu.
Confirm, Start, or Right
  Activate a menu item, or cycle through options.
Left
  Cycle through options the opposite direction, or back up.

Play Game takes you to the game selection screen, and is probably what you want to select. The Map Keys option takes you to a screen to map your keyboard and joystick on. After you do this once your settings will be saved, and you'll only need to remap it after you change adapters or joysticks.

The other choices let you change `pydance`'s global configuration, or your theme settings.

Game Options
  Autofail
    Stop the song and go to the grading screen when all players have failed it.
  Assist Mode
    Play a click, or a unique sound for each direction, when an arrow should be hit.
  Announcer
    Set your announcer theme.
  Themes...
    Set your graphical themes for all the different modes `pydance` supports.
Graphic Options
  Animation
    Animate arrows as they scroll up the screen (if your theme supports it). Turning this off may increase your framerate.
  Arrow Effects
    Have arrows "explode" at the top of the screen by rotating and scaling them. Turning this off can result in a higher framerate.
  Backgrounds
    Turn background images on or off. This won't help your framerate.
  Brightness
    Adjust the brightness of background images.
  Lyrics
    Display lyrics during songs. Turning this off may increase your framerate slightly.
  Lyrics Color
    Set the color of displayed lyrics.
Interface Options
  Save Input
    When `pydance` exits, it can save your input settings, or forget about them. Turning this off makes it forget them.
  Song Previews
    Turning this off disables the song clips that are played in the song selector. Selecting "Safe" means that Ogg Vorbis files will be previewed, but MP3s won't. If you're having trouble with `pydance` crashing while previewing MP3s, set this to Safe.
  Folders
    If you have over 60 songs or courses, folders will be displayed in the song and course selector for your convenience. If you want to view them all in one display, you can turn these folders off.
  Timer Display
    Turning this on results in a game timer being displayed at the top of the screen (in seconds), and an FPS counter in the lower left corner.
  Font
    Select the font theme being used. Current choices are the pygame default and VLGothic for Asian fonts. Requires restart.

## Game Types

The game selection screen is the one you'll see first after selecting "play game". Here, you select what panels or controller you want to use, how many people are playing, and whether you want to play individual songs or a sequence of them.

Up, Down
  Change your game, mode, or interface.
Confirm, Start
  Advance your selection.
Cancel
  Back up or go to the menu.

### Panel Layouts

3, 4, 5, 6, 7, 8, or 9 panel
  Play "regular" dancing games. The directions used are highlighted on the displayed dance mat. Note that many mats don't have a center button, and so you won't be able to play 5 or 9 panel.
Parapara
  Use the top half of the mat (left, up left, up, up right, and right) to dance.
DMX
  Like the DanceManiaX game, use the upper and lower parts of the sensors, or left, up left, up right, and right.
EZ2 and EZ2 Real
  Use three direction arrows, and left, down left, down right, and right for the circular buttons. EZ2 only uses the top circular ones, and EZ2 Real uses all four.

### Game Type

Single
  One player, one controller.
Versus
  Two players on separate controllers, with the same steps available to both. Player one will be on the left side, and player two, on the right.
Couple
  Two players, but with different steps available for each. Both players must play the same difficulty level.
Double
  One player on two controllers! You have to cross over between them as you play.

### Interface

Normal
  Select one song at a time to play.
Nonstop
  Select a "course" of songs to play, without breaks in between. `pydance` comes with several courses, and you can add your own.
Endless
  Select your difficulty level, and then keep dancing until you fail.

The game selector will display modes you don't have any available steps for, so after selecting your interface you might find out you need to back up and pick different options.

## The Song Selector

The song selector is one of the "main screens" of the `pydance` interface. This is where you pick the song you want to play, and the difficulty of it.

If you have more than 60 songs, the song selector will start up in "folder mode", where your songs are organized into folders by title, artist, BPM, mix name, difficulty level, or difficulty rating. You can turn off folders in the Interface Options menu; they are automatically disabled if you have fewer than 60 songs.

When a folder is selected, the number of songs inside it will be displayed. When a song is selected, the title, artist, and BPM of the song will be displayed, as will each player's selected difficulty, the rating of that difficulty, and the top score on that difficulty.

Up, Down
  Select a song or folder
Page Up, Page Down
  Move up or down 7 items a time in the song list
Left, right
  Change your difficulty (if the song has more than one)
Confirm
  Open a folder, or start a song
Cancel
  Close a folder (and return to the folder list), or exit (if currently viewing the folder list, or folders are turned off)
Start
  Switch to the Player Options screen
Select
  Go to a random song, in the current folder (if you're in a folder) or selected from all your songs (if you're viewing the folder list)

In addition to a name, each difficulty has a numerical rating, usually on a scale of 1 to 9. The `pydance` tutorial song has a difficulty of 0, and some very hard songs may have difficulties above 9.

### Song Difficulties

Different games have used different names to refer to the same difficulty level. For example, the easiest game mode is called "easy" in TechnoMotion, "basic" in early versions of DDR, and "light" in later versions. `pydance` uses the same colors to indicate what difficulties have different names, but are the same. These colors are also used on the nonstop screen, where only the first letter of the difficulty is displayed.

White
  Beginner, very easy
Orange
  Basic, light, easy
Red
  Trick, another, medium
Green
  Heavy, maniac, hard
Purple
  Crazy, hardcore, smaniac, expert

The names we recommend using are beginner, basic, trick, maniac, hardcore (the names early DDR versions used, and the most well-known), or beginner, easy, medium, hard, expert (which are the easiest to understand for new players).

## Players' Options

Pressing Start on any of the song selection interfaces (the song selector, nonstop, or endless) takes you to the players' options screen. From here, you can change many per-player settings (sometimes called "modifiers" or "mods"), as well as some global ones, like the type of lifebar used.

When you exit the options screen, both players' options are saved between songs. If you exit from the song selector (and go back to the main menu or game selection screen) only the first player's are remembered, and set as the default for both players. If you exit `pydance`, these options are all reset.

There are too many different options and settings to explain here, but each option has a description that is displayed with it when you select it. If you're not sure what something does, just try it out!

Up, Down
  Select an option
Left, Right
  Change the value of the current option
Start, Confirm, Cancel
  Return to the song selector

## Nonstop Mode

`pydance` lets you play several songs in a row, also called a "course". In nonstop mode you to select courses to play. The course selector works much like the song selector, except you can't select difficulties. Again, if you have over 60 courses, a folder display will be on by default.

Up, Down
  Select a song or folder
Page Up, Page Down
  Move up or down 4 items a time in the course list
Confirm
  Open a folder, or start a course
Cancel
  Close a folder (and return to the folder list), or exit (if currently viewing the folder list or folders are turned off)
Start
  Switch to the Player Options screen
Select
  Go to a random course, in the current folder (if you're in a folder), or out of all your songs (if you're viewing the folder list)

### Included Courses

`pydance` comes with two sets of courses that you can play, without having to install them.

Player's Picks
  The Player's Picks courses are courses that changed based on what songs you play in the regular game mode. The courses contain songs with your best or worst scores, or songs you have played often ("Likes") or least ("Dislikes"). You must play songs at least once for them to appear anywhere on these lists (even in Dislikes). Songs played in Nonstop or Endless mode don't affect these lists.
random.choose(songs)
  These courses consist of randomly selected songs, and will be different each time you play them. In the All Random course, even the difficulty you play on is random each time.

## Endless Mode

If all you want to do is play a lot of songs in a row, Endless Mode will keep selecting songs for you based on a preferred difficulty until you fail. If you're going to play endless mode, you probably want a lot of songs available. Otherwise it will get repetitive, or you won't have enough songs to match both players' criteria.

Up
  Select difficulty by name
Down
  Select difficulty by rating
Left, right
  Change your difficulty (left is easier, right is harder)
Confirm
  Start playing until you fail
Cancel
  Return to the game selector
Start
  Switch to the Players' Options screen

## Mapping Keys

These is the screen where you can set up input. Each direction, plus start and select, can have one keyboard key and one joystick button assigned to it.

The key mapping screen is only responds to the keyboard, and isn't affected by your key mappings (so in case you screw up, you can fix it). It can only be controlled by the arrow keys, and enter. Note that if you map your regular arrow keys, enter, or any of the other automatically configured keys here, they will only work as their new function, not their old one.

Arrow keys
  Move the selector (the white highlighted key)
Enter
  Prompt for a new key or joystick button.
Escape
  Cancel mapping of a key, or return to the main menu

# Tips

Don't return to the center after each step. This creates unnecessary foot movements. While this might make it easier to keep your bearings on simple songs, it makes harder and faster ones nearly impossible

Try practicing songs on 1.5x or 2x or one of the constant BPM modes. Some songs, especially slow ones, are easier to read on higher speeds or when the scrolling speed is constant.

Don't stomp. Stomping might help you pick up the beat better, but it also tires you out much faster. When you're tired, you move slower and less accurately, and begin missing the beat anyway.

Remember, the steps go with the music. It can be hard to hear the part of the music the steps are following, especially if it's not the main beat of the song. Try listening to the song with headphones while watching the steps, and find which part of the rhythm the steps follow.

Know your limits, and stay healthy. Keep hydrated; drink water between songs. If you twist an ankle or injure yourself, take a break. Stretch before and after playing.

# Important Files

## Main Configuration

The file `rc_path/pydance.cfg` is where your options are stored. This file can be edited in a plain text editor. Most of these can be changed by using the menus in the game, but the following ones aren't (0 means off, and 1 means on):

autogen 1|0
  On by default. If this is turned off, `pydance` won't automatically generate steps for other modes when it knows about 4 or 5 panel steps.
grading 1|0
  If this is off, `pydance` won't display the grading screen after a song.
showcombo 1|0
  If this is off, `pydance` won't display your combo count.
stickycombo 1|0
stickyjudge 1|0
  If these are off, `pydance` will remove the combo count or step judging text from the screen after a few seconds.
masteroffset [number] (default 0)
  Some systems have speakers or displays that take measurable time (in terms of affecting gameplay) to output a signal. If you have one of these, you can add an offset in milliseconds to every song you have. This should not be used if you have a lot of step files that are a specific number of milliseconds off. If you use it for this, all new files you get will be wrong, and no one else will be able to use your original files.
onboardaudio 0|1
  Some systems (especially laptops) use sound cards or drivers that resample sound in strange ways, which may make `pydance` play songs such that they "drift" in relation to the steps. If you seem to be having drifting issues in all the songs you play, you should try turning this on.
songdir [dir1:dir2:dir] (or on Windows, dir1;dir2;dir3)
  This is a list of directories where `pydance` should look for songs (.dance files, backgrounds and banners, and the audio itself). Generally installing `pydance` gives you a system-wide location to place songs (that all users will have access to), and a local one in your home directory.
coursedir [dir1:dir2:dir] (or on Windows, dir1;dir2;dir3)
  This is a list of directories where `pydance` should look for courses (.crs files). Installing `pydance` gives you a system-wide location to place courses (that all users will have access to), and a local one in your home directory.
usepsyco 1|0
  Try to use the Psyco optimizing compiler for Python (http://psyco.sf.net). This is on by default, and can give 30-50% speed gains on slower systems. However, it also uses substantially more memory (which is usually not a problem, since `pydance`'s code memory footprint is small relative to its song data). Psyco is currently only available for IA32 (Intel and AMD) systems.

## Input Configuration

`rc_path/input.cfg` contains your keyboard and joystick mapping. This is a "pickled" Python file, and can't be edited in a text editor. It will be automatically regenerated, so if you badly mess up your input settings, just delete this file to restore the controls to their defaults.

## Records

`rc_path/records` stores your best grades on each song. It is also a pickled Python file. Deleting this will reset all your grades.

# Creating .dance Files

.dance is designed to be easily written by hand, and work for all possible dancing or beat games. If you're interested in writing tools to work with .dance files, read the `docs/dance-spec.txt` file included with `pydance`.

.dance files are broken up into 3 parts — the header information (often called the metadata), the text information, and the step information. All parts are in UTF-8 encoding (which is compatible with standard ASCII), and all filenames in .dance files are case-sensitive. If you begin any line with a #, it will be ignored as a comment.

## Header Information

The header gives important information about the song that `pydance` uses to load or categorize it. A sample header (for, mysong.dance) might look like:

    filename mysong.ogg
    title My Song
    artist Me & I
    author Also Me
    banner mysong-ban.png
    background mysong-bg.jpg
    bpm 140.2
    end

The header must end with 'end'.

### A List of .dance Tags

filename
  The music file to play when the steps are loaded. There is no default setting; you must specify a music file to load the steps.
title
  The title of the song.
subtitle
  The subtitle of the song (displayed in a smaller font underneath the title).
artist
  The artist or composer of the song.
mix
  The mix of the song (where it will appear in "Sort By Mix" mode).
bpm
  The beats per minute of the song.
bpmdisplay
  A list of BPMs (separated by commas) that will be displayed on the song song selector.
gap
  The time, in milliseconds, between the start of the arrows, and the start of the song. If the first beat occurs 300 into the song, this should e.g. be -300.
startat, endat
  Second offsets into the music at which to start playing it, and end playing it. Normally this is the start of the song and the end of the song, and since music files are large, it's preferred that you cut them down to the proper size rather than using these tags.
banner, background, cdtitle
  Images to go with the song. The banner is a 256x80 image that will be displayed on the song selector. The background is 640x480 or 320x240 and will be displayed while the song is playing. The CD title is a 64x40 (or so) image to be displayed on the song selector, as well.
preview
  Set the time and length of the preview to be played in the song selector. `preview 10, 15` plays a 15 second preview, starting 10 seconds into the song.
md5sum
  The MD5 checksum string of the music file, to verify whether or not the correct one is being used.
valid
  If `valid 0` is in the header, then this file won't be selected for endless mode, random courses, or when pressing select.
revision
  The last date the file was modified, in YYYY.MM.DD format.
movie
  A background movie to play with the file. `pydance` currently only plays MPEG-1 files, but .dance files can specify any format.

## Text Data

The text data section contains a description of the file, and lyrics. Both sections are optional.

### The Description

The description section contains a description of the song. The format roughly follows the DPKG description format: All lines of text start with a space. Whitespace, including newlines, is ignored. A period ('.') on a line by itself (with a space before it!) is to be interpreted as a paragraph separator. An 'end' on a single line, with no space before it, ends the description. e.g.

    DESCRIPTION
     This is a description of the file. It is not
     particularly interesting, but here it is.
     Hooray.
     .
     Here is another paragraph.
    end

### Lyrics

The lyrics section contains lyric timing information. The format of each line is a float, an integer, and then a string. The integer specifies the lyric "channel"; lyrics in the same channel should overwrite each other, appear in the same place on the screen, etc. The float is the time into the song during which the lyric should appear, irrespective of the 'gap' value. e.g.

    LYRICS
    1.0 1 I will be displayed 1 second into the song.
    2.0 2 Two seconds in and elsewhere on the screen!
    3.0 1 I'll cover up the first lyric since we're on the same channel.
    end

## Step Data

Step sections must have at least three lines. First the game, then the difficulty and rating, and at the end, "end". In between that can be any number of step specifiers, e.g.

    SINGLE
    MANIAC 8
    q 1000
    q 0001
    end

This makes steps for SINGLE (4 panel, 1 player) mode, MANIAC difficulty, with a rating of 7. First a left step, then a right step, and then the song ends.

The string of numerals indicates which directions to press at that time; from left to right they are the same as the directions displayed in `pydance`'s top arrows left to right (e.g. left, down, up, right for 4 panel). A 1 indicates a normal arrow or the end of a hold arrow; a 3 indicates the start of a hold arrow; a 5 indicates a secret arrow.

.dance has the following types of notes (specified by a single lowercase character starting the line) (a "beat" is a non-overlapping but touching pair of arrows, on 1x speed):

o | whole | 4 beats
h | 1/2 | 2 beats
q | 1/4 | 1 beat
e | 1/8 | 0.5 beats
w | 1/12 | 0.33 beats
s | 1/16 | 0.25 beats
f | 1/24 | 0.16 beats
t | 1/32 | 0.125 beats
u | 1/48 | 0.083 beats
x | 1/64 | 0.0625 beats
n | 1/192nd | 0.02083 beats

.dance also has single uppercase character commands. `B [new BPM]` changes the BPM at that point to a new value. `S [seconds]` stops the arrows at that point for a certain number of seconds. `L [channel] [text]` displays a lyric, on a particular channel, with the given text (this lets you have different lyrics for each difficulty).

If you're making double or couple steps, separate the two players' steps with spaces, like `q 1001 0110`.

The game modes that `pydance` supports follows: SINGLE, VERSUS, COUPLE, DOUBLE (these are for 4 panel mode), 3PANEL, 3VERSUS, 3COUPLE, 3DOUBLE, 5PANEL etc, 6PANEL etc, 8PANEL etc, 9PANEL etc, EZ2SINGLE, EZ2VERSUS, EZ2COUPLE, EZ2DOUBLE, EZ2REAL, REALVERSUS, REALCOUPLE, REALDOUBLE, PARAPARA, PARAVERSUS, PARACOUPLE, PARADOUBLE, DMX, DMXVERSUS, DMXCOUPLE, DMXDOUBLE. The definitive version of this list is in the `games.py` file. If steps aren't found for a versus mode, the single mode steps will be used. If steps aren't found for any mode but they exist for 4 or 5 panel, then steps for every other mode will be autogenerated (but they might not be very fun).

# Creating Graphical Themes

The easiest way to explain graphical themes is to look at the existing ones, so you should do that before reading on. These are in `themes/gfx/NxN`, where N is some number, the dimensions of the arrow.

Every theme must contain a file `is-theme` (no extension) in the same directory.

## The Arrows

`pydance` uses one file per arrow direction, but it can also rotate arrows 90 degrees if necessary; so if you have an up arrow and a diagonal up right arrow, it can make all 8 directions (minus center). Each file is named `arr_type_dir_<number>.png`. The "type is one of c ("colored" arrow, the ones that scroll", n (the top arrows that flash), or s ("stepped", the top arrows that are displayed when you step on them). If the type is n, the number must be 0; if the type is s, the number must be 4. Otherwise, for color arrows, 0 means on-beat arrows (quarter notes), 2 is for half-beat arrows (8th notes), and 1 and 3 are for all other arrows; 1 and 3 will be alternated between if a lot of arrows on the beat or half beat occur in a row.

Arrows are animated if there is more than one NxN image tiled in them (e.g. a 64x64 arrow that is 128x128 has four frames of animation, tiled 2x2). The vertical tiling is animated during the space of one beat. The horizontal tiling is animated over beats, and loops when it reaches the end. So a 168x112 image for a 56x56 arrow, contains six frames of animation (3x2). In the space of one beat, it loops over the first three frames, and then over the next beat, it goes to the next three frames, and then back to the first three.

## The Lifebar

You also need to provide a lifebar.png, an oni-bar.png, and an oni-empty.png. lifebar.png should be 408x28 pixels, at least. This is in turn split into two 204x28 images; the left half should be the full lifebar, and the right half should be the empty one. If you want to animate the lifebar, stack images on top of each other (e.g. 408x56, 408x84, and so on).

oni-bar.png can be any size, and is the "bar" that will be displayed in your battery lifebar. It will be scaled to fit depending on how much life the player can have. oni-empty.png is a 204x28 image that the scaled oni-bar.png image will be displayed over.

## Zipping Themes

If you want to distribute your theme as a .zip file (recommended for completed themes), make it so that it unzips to the current directory, e.g. the file names are just `arr_n_d_0.png` instead of `mytheme/arr_n_d_0.png`. Make sure the is-theme file gets included.

# Creating Font Themes

Each font theme has a configuration file, `themes/font/theme.cfg`, containing the following sections:

`[global]`
  Settings global to the theme and theme defaults:
  `title=theme_name`
    The name under which the theme appers in the menus and in the configuration file.
  `font=font_file.ttf`
    Filename of the default font for this theme. If missing, the default Pygame font is used.
`[purpose]`
  Specification of font and size to be used for each UI element. See the included font theme configuration files for the list of elements to be specified. Note that only `size` option needs to be specified.
  `font=font_file.ttf`
    Filename of the font to be used for this element. If missing, the font specified in the `[global]` is used.
  `size=font_size`
    An integer specifying size for fixed-sized elements, maximum size for elements whose font size is adjusted to fit in a given width, and base size for elements whose scaling is handled by the UI code.

# Translating `pydance`

`pydance` uses `gettext` for internationalization, with the following languages currently supported:

- English (default)
- Catalan

To create a new translation on a POSIX system, begin by executing the following in the `pydance` source directory:

    pydance$ ./setup.py                         # Create Makefile
    pydance$ make uptrans                       # Create pydance.pot in po/
    pydance$ cd po
    pydance/po$ mv pydance.pot XX.po            # XX is the code of the language.

Then, edit `XX.po` with the translations. See GNU `gettext` Manual for information on this format. Finally, reinstall `pydance` or run

    pydance/po$ make generate

This will create a `mo/` directory with compiled translation files.

# Contact the Developers

## Email

There are two mailing lists for `pydance`. The first is pyddr-discuss (subscribe), which is for general discussion of `pydance`, questions about running it, making dance files, announcements of new releases, and so on. It is low traffic, at most 10 or 15 messages a month, and subscribing is recommended if you use `pydance`. The second is pyddr-devel (subscribe), which is a list for discussing `pydance` development. This list is even lower traffic, containing mostly release announcements. This is a good place to send patches or bug reports.

If you don't want to sign up for a mailing list but do want to report a bug, you can email the Debian Bug Tracking System at submit@bugs.debian.org. The first line of your email should be "Package: pydance".

Simon Tatham (who probably doesn't even know about `pydance`) has written a good document on how to report bugs in any program.

## IRC

`pydance` has an IRC channel, #pyddr, on irc.freenode.net. It is usually active, and can help you fix problems with `pydance` (if you've already tried the instructions here, and the ones in the official FAQ). The main developers are in the channel as "Pavel" (Pavel Krivitsky) and "P2E" (Brendan Becker). This is not, however, a good place to report bugs, since they can get lost easily.

# FAQ

This is not the official `pydance` FAQ, which you should check in addition to this one before asking questions. This FAQ deals with very frequently asked questions with unchanging answers.

What is 'pyDDR'?
  Before version 0.7.2, `pydance` was named pyDDR. This was because it only played DDR at the time. Now, in addition to being possible trademark violation, the name is inaccurate; `pydance` plays many dancing games in addition to Dance Dance Revolution.
What is 'Bemani'?
  Bemani is the name of Konami of Japan's music game division, that produces many of the popular arcade dancing and music games. Other non-Konami music games are also often called "bemani" by association. The word itself is a shortening of "Beatmania", the first beat game produced by Konami.
Where can I get songs?
  Aside from the free songs available on the `pydance` site, there are some places to get other songs and steps (often called "simfiles"). BemaniStyle maintains an enormous database of files people have created, usually in .sm or .dwi formats. DDRUK has simfiles for most of the official DDR songs, available via BitTorrent. However, downloading any of these songs may be copyright infringement.
Why does `pydance` crash with a segmentation fault, or "parachute error"?
  You are trying to play MP3s of a type that is not supported by SDL_mixer. Change your song preview mode to "Safe". If that doesn't work, try converting your songs to Ogg, or removing the tags (instructions on how to do this are available in the official `pydance` FAQ.

# License

This document is Copyright © 2004–2008 Joe Wreschnig and Pavel Krivitsky, and may be distributed and modified under the same terms as `pydance` itself. Many games and companies referred to above are trademarks of their respective mark holders, and no challenge is made to the validity of those marks; the only name we claim as ours is 'pydance'. Images from Level Six used with permission.