LaunchBox Shell for DOSBox 1.0

LaunchBox Shell for DOSBox is a single EXE file that you can copy next to an MS-DOS game to automatically and easily be able to play and install it. The focus here is on ease of use, portability, and easy distribution.

Why was this built?

I built this because I wanted to upload some old abandonware MS-DOS games to archive.org, and I realized that most users would have difficulty playing them without some help. I built LaunchBox Shell for DOSBox to be able to be easily distributed with a single MS-DOS game to make it exceedingly easy to play. In addition, I wanted to preserve the entire MS-DOS experience, including the installation program. LaunchBox Shell for DOSBox can be distributed next to a CD image (ISO or BIN/CUE) file and automatically help the user run the installer and then play the game.

System Requirements

LaunchBox Shell for DOSBox runs on the .NET Framework 4.6, which is automatically included on every install of Windows 10, and is already installed on most Windows 7 installations. Therefore, you should have no problem just distributing the "Play with DOSBox.exe" file only, and it should just work on all Windows 10 systems (and most Windows 7 systems). No other libraries are required for it to run.

How to Use

In general, using LaunchBox Shell for DOSBox is as easy as putting the "Play with DOSBox.exe" file next to the game files and launching the EXE. That said, there are a number of caveats and best practices, so it's best to follow the steps from one of the three sections below, depending on what type of files you're using.

How to Use with an ISO or BIN/CUE CD Image File

If you have an ISO or a BIN/CUE CD image file of the original MS-DOS disc, do the following:

1. Rename the ISO or the BIN/CUE files to match the full name of the game. Make sure that you update the path to the BIN file in the CUE file if you change the name of the BIN file (the CUE file can be edited with a text editor).
2. Copy "Play with DOSBox.exe" into the same folder as the CD image files.
3. Download a screenshot of the game (in either PNG or JPG format) and place it also in the same folder (ideally also rename it to match the full name of the game). This step is optional; no image will be displayed in the app if there is no image in the folder.
4. Run the "Play with DOSBox.exe" file and test installing and playing the game to make sure that it works properly before distribution.
5. If distributing, delete the "DOSBox" and "Game Files" folders that were created in order to save disk space (or you may keep them so that the user does not have to run the MS-DOS installation program).

How to Use with MS-DOS Game Installation Files

If you have the MS-DOS installation files for a game, but do not have an image of the original media, do the following:

1. Create a new folder and place the "Play with DOSBox.exe" file into that folder.
2. Create another new folder inside of the above folder, and name it with the full name of the game. Place the MS-DOS installation files inside of this folder.
3. Download a screenshot of the game (in either PNG or JPG format) and place it in the same folder as the "Play with DOSBox.exe" file (ideally also rename it to match the full name of the game). This step is optional; no image will be displayed in the app if there is no image in the folder.
4. Run the "Play with DOSBox.exe" file and test installing and playing the game to make sure that it works properly before distribution.
5. If distributing, delete the "DOSBox" and "Game Files" folders that were created in order to save disk space (or you may keep them so that the user does not have to run the MS-DOS installation program).

How to Use with Already-Installed MS-DOS Game Files

If you have the installed MS-DOS game files, but do not have the original media or the game's installation files, do the following:

1. Create a new folder, name it with the full name of the game, and place the "Play with DOSBox.exe" file into that folder.
2. Create a new "Game Files" folder inside of the above folder, and place the installed MS-DOS game files into that folder.
3. Download a screenshot of the game (in either PNG or JPG format) and place it in the same folder as the "Play with DOSBox.exe" file (ideally also rename it to match the full name of the game). This step is optional; no image will be displayed in the app if there is no image in the folder.
4. Run the "Play with DOSBox.exe" file and test playing the game to make sure that it works properly before distribution.
5. If distributing, delete the "DOSBox" folder that was created in order to save disk space.

Known Issues

• Currently, multi-disc games are not supported. This is planned for a future release.
• Games that run straight from the CD and don't copy any EXE, COM, or BAT files over to the hard drive do not currently work. A fix for this is also planned for a future release.
• Game disc images that don't have an install or setup file in the root of the disc will not currently work; these game discs are relatively rare, but they do exist (usually they're discs that include versions for both DOS and Windows). A fix for this is planned as well.
• Support for floppy disk images is planned, but not yet available in version 1.0.
• The goal of this application is to make as many games as possible "just work" without any custom configuration; however, there are bound to be games that do not. If you run across one of these games, please report it in the Comments section, and we'll do our best to make it work for the next version. You can also try the Debugging section below.

Debugging

If a game is not working, it's usually because the game's installer or game play application can't be found, or the wrong application is chosen. Until we test every single MS-DOS game out there (not really possible), this will always be an educated guess. If a game isn't working, here are some troubleshooting steps:

1. Go to the Advanced Configuration tab, and then the Debugging tab, and uncheck the box to "Automatically Exit DOSBox". This will allow you to see any error messages that appear on screen.
2. In the same tab, check the box to "Show MS-DOS" commands. This will allow you to see the commands that LaunchBox Shell for DOSBox is running, and it might give you a clue as to what the issue is.
3. Start the game (or the installer) and observe any error messages that come up.
4. Most likely these are the result of the wrong startup files being chosen, so type "DIR *.EXE" (without the quotes) and press Enter to see what files are available. If you see a file like looks like the right file instead, go ahead and type that file name and press Enter, which may make the installer or the game work. However, you will need to do this every time to start the game, so please report the issue in the Comments section so we can fix it.
5. If no EXE file is found that works or makes sense to run you can try typing "DIR *.COM" or "DIR *.BAT" and pressing Enter instead.
6. You can exit DOSBox by typing "EXIT" (without the quotes)  and pressing Enter.

FAQ

Doesn't LaunchBox already do this?

Yes, but it doesn't work well to distribute with games, for obvious reasons. In addition, there are some improvements to the way games are handled that are not yet in LaunchBox. We plan to integrate the changes here very soon, however.

How does LaunchBox Shell for DOSBox determine the name of the game that is displayed?

It does its best to gather it from wherever it can. When using a disc image, it will take the game's name from the file name of the disc image. When using installation files, it will take the game's name from the folder name of the installation files. Otherwise, it will try to get the game's name from any image files, or from the name of the parent folder.

How do I save the DOSBox configuration for distribution?

If DOSBox needs a custom configuration for the game, you can tweak the settings under the Advanced Configuration tab. When you play or install the game, those settings will be saved to any "dosbox.conf" file that is found anywhere inside of the application folder, or a new one will be created in the DOSBox subfolder. To save these settings for distribution, you can simply distribute the dosbox.conf file with the game. The dosbox.conf file can be kept either in the DOSBox folder, or in the root application folder. However, it is not advised to place it in the "Game Files" subfolder, as that folder is removed when the game is uninstalled via the interface.

Can I use a custom version of DOSBox, such as an older version or a distribution like DOSBox-X?

Yes, you should be able to use any custom version of DOSBox, though we have not tested it against any other versions. The version that is included inside of the "Play with DOSBox.exe" file is DOSBox 0.74-3 (the latest version at the time of this release). To use a custom version, simply overwrite the files in the DOSBox subfolder (these files are created whenever you install or run the game). LaunchBox Shell for DOSBox should not overwrite any custom DOSBox files that you place into this folder.