            DosCollection DosShell Launcher v1.0

The DosShell launcher is designed to make the launching of games
included in the DosCollection as seamless as possible.

Index:

1.  Quick Starts Guide
2.  About the DosShell launcher
3.  Relative Paths
4.  Using the DosShell launcher
5.  DosBox Commands
6.  Game Installation
7.  Using Mala
8.  FAQ
9.  Credits
10. Contact



------------------------------
1. Quick Start Guide
------------------------------

1.  Place DosShell on any drive, retaining its directory structure.  
    ie: C:\DosShell\
	(directories explained in Section 2)

2.  Place your DOSCollection in the DOSCollection Directory

3.  Install DosBox 0.70 to the same drive in its default directory.
    (If using a newer version make sure to pay attention to step 5)

4.  Run SETUP.BAT. Choose 1 (Install) to scan your games and copy launch
    files for the games you have (this is mainly designed for those whom
    have selectively downloaded from the torrent, or want to cut down the
    launch menu by removing some games, but it MUST be run)

5.  Step 2 of the launcher will update your launch files if you wish to
    use a newer version of DosBox.  Simply read through the given
    instructions, choose a version, and all the files will be updated.

6.  Launch games by either:
	A: Running the launch files in the Launch folder
	or
	B: Using the customized MaLa frontend.

For more information on using the frontend please see Section 7.


------------------------------
2. About the DosShell Launcher
------------------------------

The DosShell uses several directories.  Here is an explanation of
what purpose they serve:

Capture         - If you take screen shots using DosBox, they will
	       	  end up here.
DOSCollection   - Place your DOSCollection games here
Launch	        - This is where the launch files reside
MALA (optional) - The GUI frontend customized for DosShell
Play            - Where DOSCollection games are decompressed to
Snaps           - Screenshots for use in MALA
Util            - Various tools/configs used to make your games playable

The DosShell does not modify your DOSCOllection files  in ANY way.  It
never recompresses the games, which keeps the collection completely
pristine for seeding.

After launching any game you will be asked if you wish to keep
the game decompressed.  If you choose No, the game directory will
be erased and the next time you play the game will start from scratch.
If you have save games, custom configuration files, or just don't
want to wait for it to decompress/install again, then make sure you
choose Yes to keep it decompressed.

Launch files for nearly every title in the DOSCollection have been
included.  Omissions are primarily windows programs, scanned
documents, and add on packs which require manual installation or are
installed via the main program.

ie: Links LS has several add-on courses, which can be installed through
    a menu in the Links LS launch file rather than indivual launch files
    for each course.

On most Add-On packs I have designed the launcher to install
the original game and then decompress the Add-On into the proper
directory.  For example:

If the user runs Duke Nukem 3D: Duke it out in DC Add on, it will
first decompress Duke Nukem 3D into the directory, and then install
the add on in the same directory.  If the user runs just Duke Nukem
3D, it will be in a totally different directory.  This allows the user
to have basic and add-on versions of each game.

For games without proper sound configurations I have tried to archive
working config files for every game and have these files copied during
decompression, eliminating the need for the user to have to set up
the sound constantly.  If I missed a few games, please let me know so
I can include working config files in the next release.

Another addition is the Dos 32bit extender.  I have replaced the standard
dos4gw.exe with the improved dos32a.exe extender in games which typically
run slow.  This speeds up the emulation quite a bit, although in a few
games it destabilizes them.  Any time I noticed a crash or buggy behavior
after implementing the 32 bit extender, I removed it.  As it is difficult
to play all of these games far enough to fully test them, I am relying on
the support of those who use this launcher to report any bugs that may
be fixed by either replacing the extender with the original or vice versa.

If you wish to customize your set-up options (i.e.: reconfigure the
controls in Duke Nukem 3D, change the sound drivers in Quake, etc)
you will have to manually launch DosBox, mount the 
".\dosshell\play" directory, change directory to the game of
choice, and run the setup.

Make sure you choose to keep the game decompressed or you will loose
your custom configuration.


------------------------------
3. Relative Paths
------------------------------

I have used relative paths throughout the entire program.  This
allows you to place the DosShell on ANY drive... not an easy task
with all the virtual mounting and such (especially with the CD
based games).

The only catch is that Dosbox MUST be on the same drive, in
its default directory.


------------------------------
4. Using the DosShell Launcher
------------------------------

DosShell uses DosBox 0.70 (or newer versions if the update is used) to
launch the games.  DosBox 0.70 must be installed to the same drive that
DosShell resides on, in its default directory:
i.e.: c:\Program Files\DOSBox-0.70\

Secondly, the DOSCollection games should be placed in the 
x:\DosShell\DOSCollection\ directory (where X is whatever drive you
have it copied too).

DosShell will not work properly if it is placed in a subdirectory.

Once you have the DosCollection in this directory run the SETUP.BAT
file and choose Step 1.  This will scan your DOSCollection directory
and copy launch files for the games you have downloaded to the LAUNCH
directory.

This is primarily designed to help people who do not wish to have the
entire collection downloaded and do not want the extraneous launch files
(which will clutter up the frontend if you choose to use it).

Step 2 of the Setup batch will update your launch files to run with a
newer version of dosBox if you wish to use one.  This step is optional.

Once Setup has been run, you may launch any DOS game by running its
batch file located in the LAUNCH directory.


------------------------------
5. DosBox Commands
------------------------------

A familiarity with basic DosBox is extremely beneficial when playing
these games.  While I highly recommend reading the DosBox read me, here
are the most commonly used commands:

CTRL-F11		Slow down emulation (for games running too fast)
CTRL-F12		Speed up emulation (for games running too slow)
Alt-ENTER		Switch between Full screen and Window
CTRL-F9			Exit DosBox
CTRL-F4			Used to switch mounted images (useful for multi
			CD games).  Any game which sues this will warn
			you before launching.
CTRL-F5			Capture a screenshot.


------------------------------
6. Game Installation
------------------------------

Many games must be installed before they will run properly.  Anytime an
installation is required, DosShell typically warns you before it starts.

ALWAYS use the default directory suggested by the game installer, as
the launch files will be aimed at this directory.  If a game does not start
after you install it, choose NO when asked to keep the game decompressed.
This will allow you to run the install program again the next time you start
the game.

I have written a special install.conf file which bumps up the cycles during
installation to speed up the copy time.  So far I have not seen this cause
any problems.

Many times the game will require Sound configuration.  In most cases I have
preconfigured files that copy into the game directory for you.  Even if it asks
for your iput, my config files will generally overwrite your selections.

In the event you have to set-up sound manually, please follow these guidelines:

While dosbox emulates several different audio cards, it is highly recommended
that you always choose:

Card:		SoundBlaster Compatible/Pro/16  (NOT AWE32!)
Base/Hex:	220
IRQ:		7
DMA:		1 (sometimes 5, if 1 doesn't work)

Autodetect programs like to choose the Gravis Ultrasound.  While this should
work, I typically get notably choppy audio from that card.

Recently MT32 emulation has been added to DosBox.  This is a MAJOR improvement
for midi files.  While I have specifed MT32 emulation in some games, the 
support for MT32 came after I had started the launcher.  You can manually
set the sound in most games by running the setup file through dosbox.  This
will require a bit of knowledge on your part however, and is easiest to
do by modifying my launch files to point to the setup file rather than the
executable file.  keep in mind that some games sound horrid on MT-32...

If for any reason an installation screws up, simply choose to NOT keep
the game decompressed. This will force the launcher to start from scratch
the next time you run the game.


------------------------------
7. Using MALA
------------------------------

I have customized MaLa to run with DosShell.

When you run the install it will prompt you for the drive you have
installed MaLa on.  This will rewrite it's configuration files to
locate your games.

Now you can either create your own shortcut to MaLa or modify the one
provided (in the DosShell root directory) to launch the frontend.

Once MaLa has launched you can right click to bring up a menu and then
choose "Refresh Game List" to populate the menu. The first time you start
it the game list will be empty. Make sure to refersh the game list.

This will add all the launch files copied when you ran the setup to
the game list.

You should now be able to scroll through the list and launch any game by 
pressing ENTER.

If you have the screenshots installed, you should see them on the right.
The Left ALT key will zoom into the screen shot.

You can also use CTRL+UP ARROW or CTRL+DOWN ARROW to scroll through the game
list a page at a time.

Use the ESC key to bring up the Quit dialog, and use ENTER to accept.

At this time I do not plan to support any other front ends, although any
front end which supports batch files can be used.


------------------------------
8. FAQ
------------------------------

|General|

Q: Will the DosShell modify any of my DOSCOllection games?
A: Nope, it just decompresses them.  This maintains the integrity of your games,
   and allows you to continually seed them or pick-up right where you left off
   without ever having to recompress anything.  If you have save games and the
   such then make sure you keep the game decompressed after you play.

Q: Can I use a subversion build of DosBox or a newer version?
A: Sure, but keep in mind the games have been set up and tested with
   0.70.  For major releases run setup.bat, and choose Step 2.  Then
   choose the version of dosbox you are running.  If you have a subversion
   build or one not listed, simply install it to the default dosbox directory,
   ie: c:\Program Files\DosBox-0.70

|Running a Game issues|

Q: My game is running SO slow or WAY too fast!
A: If the game is running too fast you can slow down DosBox by hitting CTRL-F11.
   If the game is too slow you can try hitting CTRL-F12 to speed up emulation,
   but obviously you’re limited to the speed of your computer.

Q: I'm playing some old game and I can't figure out the keys!
A: Trial and Error my friend.  I always check the WSAD and INS/DEL/PGUP/PGDN keys
   first.  After that I just start trying every key to see what happens.  Don't
   forget to turn numlock on or off and trying it that way as well.

Q: Can I use a joystick?
A: Yes, but I have disabled joystick emulation in the CONF files because many
   games automatically detect the joystick and try to force you to use it 
   whether you have one or not.  To enable your joystick go to the
   ".\util\conf" directory and open the DOSBOX.CONF file with notepad. Go to
   the JOYSTICK section and change:
   joysticktype=none
   to
   joysticktype=auto
   Other options can be changed here as well.

|Game Installation Issues|

Q: HELP - it is asking me to install something!?!?
A: Always accept the default directories and read Section 6.

Q: I screwed up installing the game, and now it won't run.
A: Simply choose to NOT keep the game decompressed when exiting.  This will
   erase all your horrible mistakes and allow you to start fresh next time.

Q: Some of these installations take forever... Is there anything I can do?
A: Sure, speed up the cycles. You'd be surprised how fast some of these games
   install when the cycles are set around 20000. =)

|Sound Issues|

Q: What are the optimal sound card settings?
A: SB/SB16/SBPRO at base 220, IRQ 7, and DMA 1.  Gravis and Roland will work as
   well, but they aren't always reliable.  Sometimes I get garbage when they
   play.

Q: How do I customize my setup file, I want different controls/sound/etc?
A: Learn to run DosBox manually.  Section 2 explains this a bit more in
   detail.  After the initial game setup, you can go in and change the
   game config's without them being overwritten.

|Other Stuff|

Q: The DosCollection has X amount of files but the launcher only has Y amount
   of games... what happened to the rest of them?
A: Not everything in the DosCollection is a game (or even useful).  Apps,
   windows games (which should technically not be included), and other randomness
   is not supported by this launcher.

Q: A game doesn’t work for me.
A: All broken games should have a note when you start them to warn you. If
   the game required an install, make sure you used the default drives and
   directories. If the game says it wants to install to 
   C:\GAMES\DAFFYDUCKSCRAZYASSADVENTURE
   then let it.  The way the virtual drives work, it will not actually go to
   your C drive., it will create the directory within the game directory within
   the play directory.... yes, I know that’s confusing.  Just trust me.

Q: None of the games work for me!
A: Did you place your DosCollection in the DOSCollection folder?  Did you
   bother reading the "Using DosShell Launcher" section?  Did you actually
   download the DosCollection... you know you need that as well right... this
   is just a launcher....

   If all this is true and STILL nothing works, contact me using the email below
   and we'll see what’s up.

Q: In the CONF directory (under util) there is a dosbox.conf, dosbox2.conf, and 
   dosbox3.conf.  What’s the difference?
A: Dosbox2.conf and dosbox3.conf are variations on the emulated memory.  Dosbox2
   has XMS disabled, while dosbox3 has all upper memory disabled.  This is required
   for some games such as some Ultima games and Aladdin.


------------------------------
9. Credits
------------------------------

A very special thanks to BladeHunter and Databank at The Pleasuredome.
Their arcane knowledge of batch files was extremely helpful in creating
templates for all my files, and the basis for several other batch scripts
I used to accomplish many of my tasks.

A thanx goes to Flap for reviving and updating the DosCollection.

dhuseby's contribution of the Broken Game graphic was very welcome and
appreciated.

one2three deserves credit for knocking out a ton of snaps and always
finishing the packs I sent him.  Thanks man.

Of course the authors of DosBox deserve much credit for giving us a tool
to make the enjoyment of these old programs possible.

And possibly more than anything or anyone else, thanks to The Pleasuredome
and its community for providing a base for files like this to exist and
develop from.

... and thanx to my girlfriend for not disowning me as I spent days trying to
get these ridiculous old games running.


------------------------------
10. Contact
------------------------------

You can find me at the Pleasuredome occasionally lurking the forums under
the name 'eXo'.

You can also email me at exo@theexo.com, but make sure you put something
about DosShell or DosCollection in the subject line or it probably won't
get noticed.
