
DANCE WITH INTENSITY! v1.00
===========================
(C) SimWolf            2001
===========================

1. DISCLAIMER AND TERMS OF USE
2. VERSION HISTORY
3. USING AND CONFIGURING DWI
4. DWI FILE FORMAT
     - Steps
     - Tags
     - Background Animations.
5. LIMITATIONS
6. FUTURE DEVELOPMENT AND THANKS


1. DISCLAIMER AND TERMS OF USE
==============================

This program is provided for free, as-is.  Although it has been tested on multiple systems for compatability and reliability, you run this program at your own risk.  I cannot be held responsible if the program causes file loss or other problems.

THIS PROGRAM IS *NOT* FOR SALE!!!  IT SHOULD NEVER BE BUNDLED WITH ANY OTHER FILES (MUSIC OR STEP FILES) ON ANY MEDIA, INCLUDING (BUT NOT LIMITED TO) CD's, DVD's, DISKS OR OTHER MEDIA.

This program simulates a popular arcade and home video game.  It was written to allow myself the ability to play songs from the games without having to switch CDs in my Playstation or Dreamcast, and also affords the ability to add new songs not currently available.  It also allows for playing older songs with new play modes, such as downward-scrolling arrows.  This program is being released to the public in the hopes that others would find it useful in the same manner.

As such, this program REQUIRES responsibility on the part of the end-user (ie. YOU) to use the program LEGALLY.  You should *ONLY* play songs where you:

   a) Own the game from which that music comes from.
or b) Own the soundtrack CD from which the music comes from.
or c) Legally own rights to the music being used (ie. other CDs, etc.)

I own all the available soundtracks and videogames for the music I own, and respectfully ask that you support the games and purchase them.  Thank you.


2. VERSION HISTORY
==================

v1.00 - December 14, 2001
      - first public release.  Supported are:
          - BPM changes, pauses
          - Freeze arrows
          - Split/Unison/Couple modes
          - multiple folders
          - downwards-scrolling arrows
          - record keeping
          - background animations

3. USING AND CONFIGURING DWI
============================

When you first run DWI, you will receive a warning screen about responsible use of the program.  This warning screen will appear *EVERY* time the program detects new songs.

DWI uses step-files with the extension ".DWI".  A step file goes in a subdirectory of the "DWIs" directory.  Background and Banner images for each song should be given the same name and put in a corresponding subdirectory in their own folders.

DWI supports multiple collections of songs, so you can organise your songs as you see fit.  To do this, just put the step-files in different sub-directories of the "DWIs" folder.

eg. For a song with a step-file of "abc.dwi", put into a collection called "My Songs", your directory structure should look like this:

     <install directory>
        + Backgrounds
        |    + My Songs
        |         + abc.png
        |
        + Banners
        |    + My Songs
        |         + abc.png
        |
        + DWIs
             + My Songs
                  + abc.dwi

Song Sorting
------------

When you are at the song select screen, simply press up or down to change the current collection you are in.  Songs are organized alphabetically within each collection, and collections are organized alphabetically also.

Another option is to sort your music by genre.  To activate this, go to "Options Menu", then "System Menu", and change the sort method to "GENRE" *.  This requires your DWI files to have a tag defining the genre to put the music into (see DWI format, below).  Multiple genres can be given (separated by a comma), to make the same song appear in different collections.  At the song select screen, press up or down to change the genre.

  * NB: You must exit DWI and start it again for this change to take effect.

Controller Configuration
------------------------

To change the inputs, simply go to the Options Menu from the main screen and goto "Controller Configuration".  Choose to configure either Player 1 or Player 2's inputs and you will be prompted to press each key, joystick button or dancepad square in turn.  You cannot choose a key that is currently in use.  When done, select "Return" to make the change take effect.

Gameplay Settings
-----------------

Gameplay settings such as difficulty level, danger display, and end-of-game settings are selected from the Gameplay Configuration menu from the Options screen.  These changes take effect immediately.

Sound Configuration
-------------------

The default sound settings for DWI are 44Khz, Stereo, 16-bit samples.  However, you may want to lower these settings on slower computers.

  * NB: You must exit DWI and start it again for this change to take effect.

Changing the Display from Windowed to Full-screen
-------------------------------------------------

Go to the "System Menu" from the Options screen and change the display type.

  * NB: You must exit DWI and start it again for this change to take effect.

Sound effects
-------------

Sound effects are all in the "soundfx" directory.  You can add or remove files to most directories, and the program will use the existing files during gameplay.  However, files in the root of the "soundfx" directory and those in the "attract" and "combo" directories must be the same name in order for the program to find them and play them appropriately.

4. DWI FILE FORMAT
==================

Steps
-----

DWI uses step-files that are similar to the ".MSD" file format.  However, there are new additions and some tags are treated slightly differently, so the extension was changed to avoid confusion.  DWI files with these new additions will not work properly in other simulators.

Step-patterns are defined in the same way as .MSD files - use the numeric keypad as a reference for most patterns:

  7=U+L     8=U      9=U+R

  4=L                6=R

  1=D+L     2=D      3=D+R

    (U+D = A and L+R = B)

A '0' indicates no step.  Each character defaults to one 1/8 of a beat.  Surround a series of characters with the following brackets to change the rate at which the steps come:

   (...)  = 1/16 steps
   [...]  = 1/24 steps
   {...}  = 1/64 steps

6-panel (Solo) mode uses additional characters:

-\---- = C
----/- = D

L\---- = E
-\D--- = F
-\-U-- = G
-\---R = H

L---/- = I
--D-/- = J
---U/- = K
----/R = L

-\--/- = M

MSD files from other simulators will work with DWI, with a change in the 'GAP' value being the only change usually necessary.  DWI calculates the 'GAP' value differently than other simulators that use the MSD format.

DWI does not support the BMS file format.  There is a utility available that can convert any BMS file into DWI format.  Each song only requires one DWI file for all of its steps, so if you are converting BMS files please remember that all the different difficulties of step patterns will be contained in the same DWI file.

Hold Arrows
-----------

In the DWI file format a hold arrow is signified with the ! symbol.  The string  8!8   will begin an 'up' hold arrow, and the arrow will be released the next time the program encounters an 'up' arrow: by itself or combined with another arrow (7, 8, 9, A, etc.)  The characters  7!4  would show both 'up' and 'left' arrows but only the left arrow would be held.  The format could best be described as "show!hold".

Tags
----

These tags should be in every DWI file:

#FILE:...;     - path to the music file to play (eg. /music/mysongs/abc.mp3 )
#TITLE:...;    - title of the song.
#ARTIST:...;   - artist of the song.
#GAP:...;      - number of milliseconds that pass before the program starts counting
                 beats.  Used to sync the steps to the music.
#BPM:...;      - BPM of the music

Additionally, the following tags can be given:

#FREEZE:...;   - a value of the format "BBB=sss".  Indicates that at 'beat' "BBB", 
                 the motion of the arrows should stop for "sss" milliseconds.  Turn on 
                 beat-display in the System menu to help determine what values to use.
                 Multiple freezes can be given by separating them with commas.

#BPMCHANGE:...; - a value of the format "BBB=nnn".  Indicates that at 'beat' "BBB",
                  the speed of the arrows will change to reflect a new BPM of "nnn".
                  Multiple BPM changes can be given by separating them with commas.

#STATUS:...;   - can be "NEW" or "NORMAL".  Changes the display of songs on the 
                 song-select screen.

#GENRE:...;    - a genre to assign to the song if "sort by Genre" is selected in the 
                 System Options.  Multiple Genres can be given by separating them with 
                 commas.
#CDTITLE:...;  - points to a small graphic file (64x40) that will display in the song 
                 selection screen in the bottom right of the background, showing which
                 CD the song is from.  The colour of the pixel in the upper-left will
                 be made transparent.  

Each pattern of steps for different modes have the same basic format:

#SINGLE:BASIC:X:...;
 ^      ^     ^ ^
 |      |     | + step patterns.  In doubles, the left pad's steps are given first, 
 |      |     |   then the right pad's, separated by a colon (:).
 |      |     |
 |      |     + difficulty rating.  Should be 1 or higher.
 |      |
 |      + Difficulty.  Can be one of "BASIC", "ANOTHER", "MANIAC", or "SMANIAC"
 |
 + Style.  Can be one of "SINGLE", "DOUBLE", "COUPLE", or "SOLO".  "COUPLE" is 
   Battle-mode steps.

Background Animations
---------------------

DWI additionally allows for background animations using a special script within the step-file.  A sample animation is described below:

#BACKGROUND:

  A:FILE:.\anim\animtile-1.png MULT:0,1,0.5 ANIMATE:10,250 MOVE:0,-0.01 LAYER:0;
  B:FILE:.\anim\spinbox-blue.png ANIMATE:45,25 LAYER:0;
  D:FILE:.\anim\sheep.png ANIMATE:11 MOVE:0.02,-0.01 SPACING:30,30 TRANS:2 LAYER:1;
  E:FILE:.\anim\equalizer.png ANIMATE:10,33 POSITION:-33,0 SPACING:40,40 TRANS:2 LAYER:1;
  M:FILE:.\anim\dancer-m1.png ANIMATE:24,66 SIZE:2 SPACING:30,30 TRANS:2 LAYER:1;
  X:LAYER:1 OFF;

  SCRIPT:........................
         ................B...............
         D...............A,X...............E...............B,X...............
         M...............A,X...............D...............B,X...............
         D...............A,X...............E...............B,X...............
         M...............A,X...............D...............B,X...............
         E...............A,X...............M...........0,X...;

#END;

The first part of the "BACKGROUND" definition defines the effects.  Each effect is attributed to a letter or number ("a-z", "A-Z", "1-9").  The format for defining an effect is:

   FILE:       - path to a file (required unless parameter "OFF" is given).  
                 Either a still image, or an animation (multiple frames of animation are 
                 stacked *vertically* in the image).

   MULT:r,g,b  - Red, Green, and Blue pixels in the image are multiplied by the given 
                 amounts.  This way the same image can be used multiple times and have 
                 different colours.

   ANIMATE:f,n1,n2,...nF - indicates that the FILE contains multiple frames of animation. 
                           "f" is the number of frames of animation.  Each following 
                           value is the number of milliseconds each frame of animation 
                           is displayed.  If not enough time-values are given, the last
                           given value is used.

   MOVE:x,y    - the image is moved by the given number of pixels every millisecond.

   SPACING:x,y - images are always tiled if they don't fill up the screen.  This tag 
                 allows you to add some spacing between the images by the given number 
                 of pixels horizontally and vertically.

   TRANS:c     - set to "1" to enable transparancy within the image.  If the PNG file 
                 has an alpha channel, that is used.  Otherwise, the color of the pixel in 
                 the top-left corner of the image is considered the "transparancy colour".
                 "2" does exactly the same thing, but some optimizations are made that 
                 could improve performance.  Some images will work better with '1'.

   SIZE:s      - multiplies the image size by 's' in both directions.  Must be a whole 
                 number.

   LAYER:l     - the layer to use (required):
                   0 - base layer.  Image is *always* tiled and SPACING and TRANS values
                       are ignored.
                   1 - overlay layer
                   2 - overlay layer

   KEEPPOS     - normally when a new effect is turned on, its position is reset.  This 
                 tag keeps the layer where it is, useful for keeping images moving 
                 smoothly.

   OFF         - turns off a layer, effectively making it invisible.  Will not turn off 
                 layer 0.

   ROTATEPAL:a,n,s - on an indexed-colour image (256-colours), will rotate the 
                     colour-values within the image.  "a" is the index of the first colour.
                     "n" is the number of colour-values to rotate.  "s" is the rate at 
                     which to cycle the colours.  To rotate all the colours, use 
                     "ROTATEPAL:0,256,s".

Following the effect definition, comes the actual animation script.  This is a sequence of characters in a similar way as the step-patterns are given - each character normally is 1/8 of a beat, though brackets can be used to change the time-values.  In this way, background animations can be syched to the steps.  It is suggested that the steps for "SINGLE:BASIC" are copied to after the "SCRIPT:" tag, and then the effects be set.  In this way one knows that the script will match the same length of the music.

The animations take effect as that point in the song is reached.  Multiple effects can occur at the same time if they are separated with a comma (as in the example above,  "A,X" means "Turn on 'animtile-1.png' on layer 0, and turn off layer 1 at the same time").

A period (.) means no new effect should take place at that point.  A zero (0) turns off all effects and returns the background to the original graphic.

5. LIMITATIONS
==============

Partly due to the compiler and my own lack of knowledge in some areas, there are a number of limitations imposed on the program that users should know about:

   - No more than 64 collections.
   - No more than 128 step-files in a single collection/folder
   - No more than 64 sound effects in a single subdirectory of 'soundfx'
   - No more than 2000 steps per player in a single song (or no more than 1000 jumps)
     More than that will be ignored.

The speed of the program is slower than other simulators.  The program runs smoothly on my 800MHz Athlon at default sound settings, but on slower computers the framerate will be poor.  To help, try the following:

      - Install the latest DirectX 8.1 drivers.
      - Lower the sound quality to Mono, 8-bit, and/or 11 or 22Khz.

I would like to improve the speed but I have yet to find a graphics library that does all I want (24-bit colours, 8-bit alpha-blending in sprites), so I wrote my own over TinyPTC, which is completely software-based.  If you can help, please post to the DWI forum at The Melting Pot with information.  Thanks!

6. FUTURE DEVELOPMENT AND THANKS
================================

A long time was spent making this program, and I believe that this first release is fairly complete in terms of features.  I do intend on speeding up the graphics engine at some point, but my abilities in that area is fairly limited unfortunately.  The song-select screen may be updated in a future release.  New features will be considered as resources and interest permit.

Special thanks go to DjDraftHorse for the announcer files - I think he did a fantastic job, very professional.  Also he has been a great beta-tester and a sounding board for new ideas.  Much appreciated!

BBW, for putting up with my incessant programming of the simulator and my exhorting of the joys of Bemani. ;)

Also, thank you to BemaniRuler for beta-testing the program and your enthusiasm for the project.  LagGed and the others at "The Melting Pot" for the resources available there concerning the file formats and other simulators, and his offer to host the distribution files.

Pawwaves to those in the furry community. :^)

Enjoy...
SimWolf.

http://www.teamgwailo.com/ddrpccentral/dwi
