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.
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.
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.
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.
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.
You will need Python 2.3, and Pygame 1.6. 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.
You want the Pygame kitchen sink install, which contains everything you'll need.
Download a recent version of Python 2.3, and Pygame 1.6.
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.
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).
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 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 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 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/.
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.
The most popular dance mats are for Playstation 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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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).
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.
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.
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 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, or mix name. 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.
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.
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.
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).
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!
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.
pydance comes with two sets of courses that you can play, without having to install them.
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.
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.
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. Some songs, especially slow ones, are easier to read on higher speeds.
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.
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.
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):
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.
rc_path/records stores your best grades on each song. It is also a pickled Python file. Deleting this will reset all your grades.
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". You can also email them directly to Joe Wreschnig if you don't feel comfortable using the Debian BTS.
Simon Tatham (who probably doesn't even know about pydance) has written a good document on how to report bugs in any program.
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 "piman" (Joe Wreschnig) and "P2E" (Brendan Becker). This is not, however, a good place to report bugs, since they can get lost easily.
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.
This document is Copyright © 2004 Joe Wreschnig, 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.