Difference between revisions of "Emulator:DOSBox"
(Changed "roms/dos" to "dosgames", and added subsection on AVI movie recording.) |
|||
| Line 38: | Line 38: | ||
== DOS Game Folder Structure == | == DOS Game Folder Structure == | ||
| − | Create a main folder where you will keep all your DOS games. The example used in this guide will be named '''~/ | + | Create a main folder where you will keep all your DOS games. The example used in this guide will be named '''~/dosgames'''. |
| − | Create the following subfolders in ~/ | + | Create the following subfolders in ~/dosgames: |
* '''conf''' | * '''conf''' | ||
* '''keymaps''' | * '''keymaps''' | ||
| − | * ''' | + | * '''captures''' |
| + | * '''snaps''' | ||
| + | * '''movies''' | ||
I'll get to the purposes of these subfolders in a bit. | I'll get to the purposes of these subfolders in a bit. | ||
| − | Also create a subfolder for each of the DOS games you want to set up. I will use | + | Also create a subfolder for each of the DOS games you want to set up. I will use somes favorites of mine as examples: |
| + | * '''KEEN1''' | ||
| + | * '''RAPTOR''' | ||
* '''ROUND42''' | * '''ROUND42''' | ||
| + | * '''SCORCH''' | ||
* '''XCUTE''' | * '''XCUTE''' | ||
| − | It's important that you name your games' subfolders using only eight characters or less | + | It's important that you name your games' subfolders using only eight characters or less, because actual DOS did not support file and directory names longer than 8 characters; DOSBox behaves the same way. A good rule of thumb is to name it similar to the game's main executable file. |
You'll notice that I named my game subfolders in capital letters and my non-game subfolders in lowercase letters. I use this convention for my own benefit, so I can easily differentiate those that contain game files apart from those that don't. | You'll notice that I named my game subfolders in capital letters and my non-game subfolders in lowercase letters. I use this convention for my own benefit, so I can easily differentiate those that contain game files apart from those that don't. | ||
| Line 60: | Line 65: | ||
== Batch (.BAT) Files == | == Batch (.BAT) Files == | ||
| − | Back in your '''~/ | + | Back in your '''~/dosgames''' folder, create a new text file. Name it identically to one of your game's subfolder, and give it a '''.BAT''' file extension. This is a DOS batch file. Open the file and give it text like the following: |
@echo off | @echo off | ||
| Line 66: | Line 71: | ||
round42.com | round42.com | ||
| − | ''(Unless you've already guessed, replace "round42" with the folder name and executable name of one of your games.)'' | + | ''(Unless you've already guessed by now, replace "round42" with the folder name and executable name of one of your games.)'' |
The batch file serves two main purposes: | The batch file serves two main purposes: | ||
* The first is to change the current working directory to the game's subfolder before running the game itself. | * The first is to change the current working directory to the game's subfolder before running the game itself. | ||
| − | * The second purpose is to specify the type of file being executed. A DOS game's executable file will almost always be a ''.EXE'' file. There are some rare cases, particularly with older games, where the extension | + | * The second purpose is to specify the type of file being executed. A DOS game's executable file will almost always be a ''.EXE'' file. There are some rare cases, however, particularly with older games, where the extension would be ''.COM''. COM files are executed in the same manner as EXE files. In the batch file you can specify either type, meaning you don't have to rely on a game's extension being EXE for it to be visible in your Wah!Cade game list. |
| − | The "@echo off" statement | + | The "@echo off" statement hides the batch commands from view as they are processed in the DOSBox window. It's optional, but recommended. |
Save and close the batch file. Test it: | Save and close the batch file. Test it: | ||
| − | dosbox ~/ | + | dosbox ~/dosgames/ROUND42.BAT |
If all went well, DOSBox should have executed the game. Exit the game, or force terminate using CTRL-F9 if necessary. | If all went well, DOSBox should have executed the game. Exit the game, or force terminate using CTRL-F9 if necessary. | ||
| Line 83: | Line 88: | ||
== DOSBox Configuration Per Game== | == DOSBox Configuration Per Game== | ||
| + | === Why Per Game? === | ||
| + | Due to the wide diversity of games on DOS, and the longevity of DOS as a gaming platform, it's ''critical'' to maintain individual DOSBox configurations for each game. A DOS game from 1982 is going to require a vastly different DOSBox configuration than one from 1996, because computers evolved significantly in that 14-year span. This is as opposed to console emulators, where one configuration works for all games. | ||
| + | |||
=== CONF File Creation === | === CONF File Creation === | ||
| − | On DOSBox's first run, it creates a config file in '''~/.dosbox''' named '''dosbox-version.conf'''. Copy this file to '''~/ | + | On DOSBox's first run, it creates a config file in '''~/.dosbox''' named '''dosbox-version.conf'''. Copy this file to '''~/dosgames/conf'''. |
Make as many copies of this file as you have DOS games, naming each one identically to the game's subfolder name with a '''.conf''' extension (e.g.: ROUND42.conf). | Make as many copies of this file as you have DOS games, naming each one identically to the game's subfolder name with a '''.conf''' extension (e.g.: ROUND42.conf). | ||
| Line 99: | Line 107: | ||
output=openglnb | output=openglnb | ||
| − | You will see an option called '''mapperfile'''. Set this to a (currently) nonexistent file in your '''~/ | + | You will see an option called '''mapperfile'''. Set this to a (currently) nonexistent file in your '''~/dosgames/keymaps''' subfolder. For my ROUND42 example: |
| − | mapperfile=~/ | + | mapperfile=~/dosgames/keymaps/mapper_ROUND42.txt |
| − | Adjust your settings in each of your games' conf files, making sure you have set your mapperfile paths properly for each one. Also edit the '''captures''' option. Set it to '''~/ | + | Adjust your settings in each of your games' conf files, making sure you have set your mapperfile paths properly for each one. Also edit the '''captures''' option. Set it to '''~/dosgames/captures'''. You'll see why later on. |
Some older games may require different machine types in order to work properly. For example, try setting the '''machine''' option to '''tandy''' for games that ran on the Tandy 1000 line of computers. | Some older games may require different machine types in order to work properly. For example, try setting the '''machine''' option to '''tandy''' for games that ran on the Tandy 1000 line of computers. | ||
| − | For games that did not use sound cards, you will need to make sure you set '''pcspeaker''' to '''true''' in order to hear the PC "beep" sound effects. | + | For older games that did not use sound cards, you will need to make sure you set '''pcspeaker''' to '''true''' in order to hear the PC "beep" sound effects. |
You will also see options for frameskipping, cpu type, and many others. Most of the time you can leave these as they are. DOSBox's official documentation on these options is available at this link: [http://www.dosbox.com/wiki/Dosbox.conf Dosbox.conf]. | You will also see options for frameskipping, cpu type, and many others. Most of the time you can leave these as they are. DOSBox's official documentation on these options is available at this link: [http://www.dosbox.com/wiki/Dosbox.conf Dosbox.conf]. | ||
| Line 113: | Line 121: | ||
Test a game using the appropriate conf file: | Test a game using the appropriate conf file: | ||
| − | dosbox ~/ | + | dosbox ~/dosgames/ROUND42.BAT -conf ~/dosgames/conf/ROUND42.conf |
Again, the game will come up. This time, using the options as you configured, like fullscreen. | Again, the game will come up. This time, using the options as you configured, like fullscreen. | ||
=== Run the Games' Setup Utilities === | === Run the Games' Setup Utilities === | ||
| − | Don't forget to run the setup/install utilities for the games that have them. Display modes (CGA, EGA, VGA) | + | Don't forget to run the setup/install utilities for the games that have them. Display modes (CGA, EGA, VGA), sound settings (Sound Blaster, AdLib), and controls need to be configured just as if this were actual DOS. |
Execute the setup utility with DOSBox. For example: | Execute the setup utility with DOSBox. For example: | ||
| − | dosbox ~/ | + | dosbox ~/dosgames/GAMENAME/SETUP.EXE |
| − | + | Usually, default Sound Blaster settings work just fine. Just make sure the IRQ and DMA settings you set for the game match those defined in the corresponding conf file. | |
| − | Refer to your game's | + | Refer to your game's README files or help docs for more info. |
== Key Mapping == | == Key Mapping == | ||
=== Creating a Custom Mapper File === | === Creating a Custom Mapper File === | ||
| − | While in the game, press CTRL-F1 to activate the keymapper. | + | While in the game, press CTRL-F1 to activate the keymapper. I won't go into much detail here on how the keymapper works, but complete documentation can be found here: [http://www.dosbox.com/wiki/Keymapper Mapper] |
| − | + | === Reset Mapper To Default === | |
| + | If you take a look in the '''~/dosgames/keymaps''' subfolder, you'll see that a mapper file has been created. If you ever want to reset a game's keymapping, simply delete this file and a fresh one will be generated next time you activate the keymapper while in a game. | ||
| − | === | + | == Snaps / Movies == |
| − | + | === Creating Screenshots === | |
| + | While playing a game in DOSBox, pressing CTRL-F5 will take a PNG screenshot and save it to the '''captures''' subfolder you specified in the game's conf file. It will be named the same as the game's name with lowercase letters and a numeric suffix. | ||
| + | |||
| + | Store screenshots in '''~/dosgames/snaps'''. As with all platforms in Wah!Cade, the image filenames must exactly match the names of the roms. The "roms" in this case are the batch files you created. | ||
| + | |||
| + | Follow the same procedure if you want screenshots of title screens, game-over messages, high score listings, etc. | ||
| − | == | + | === Recording Movies === |
| − | + | While playing a game in DOSBox, pressing CTRL-ALT-F5 will begin recording an AVI movie. Pressing CTRL-ALT-F5 again will stop recording and save the resulting movie in the '''captures''' subfolder you specified in the game's conf file. It will be named the same as the game's name with a numeric suffix. | |
| − | |||
| − | + | Store movies in '''~/dosgames/movies'''. As with snaps, the movie filenames must exactly match the names of your batch files. | |
| − | |||
== Adding DOSBox To Wah!Cade == | == Adding DOSBox To Wah!Cade == | ||
| − | In '''Wah!Cade Setup Editor''', under the '''Emulators''' tab, add DOSBox as a platform. Set your rom path to '''~/ | + | In '''Wah!Cade Setup Editor''', under the '''Emulators''' tab, add DOSBox as a platform. Set your rom path to '''~/dosgames''', rom extension to '''BAT''', your commandline format to '''[rompath]/[name].[romext] -exit -conf [rompath]/conf/[name].conf''', and your artwork 1 path to '''[rompath]/snaps'''. |
Alternatively, you can edit your '''dosbox.ini''' file in '''~/.wahcade/ini''' accordingly: | Alternatively, you can edit your '''dosbox.ini''' file in '''~/.wahcade/ini''' accordingly: | ||
| Line 155: | Line 167: | ||
### List Generation Settings ### | ### List Generation Settings ### | ||
| − | rom_path ~/ | + | rom_path ~/dosgames |
rom_extension BAT | rom_extension BAT | ||
dat_file | dat_file | ||
| Line 170: | Line 182: | ||
### Artwork Locations ### | ### Artwork Locations ### | ||
| − | artwork_1_image_path [rompath]/ | + | artwork_1_image_path [rompath]/snaps |
artwork_2_image_path | artwork_2_image_path | ||
artwork_3_image_path | artwork_3_image_path | ||
| Line 218: | Line 230: | ||
A game's ability to be 100% playable using MAME-like arcade controls is referred to as its [[cabinet-friendliness]]. If you're using DOSBox with Wah!Cade in an arcade cabinet, you'll soon realize that not all of your DOS games play very well using the controls, especially those that require full use of the keyboard. | A game's ability to be 100% playable using MAME-like arcade controls is referred to as its [[cabinet-friendliness]]. If you're using DOSBox with Wah!Cade in an arcade cabinet, you'll soon realize that not all of your DOS games play very well using the controls, especially those that require full use of the keyboard. | ||
| − | You will need to carefully evaluate each of your games and decide which ones are good candidates to be included in your setup. Often times a game allows you to redefine the keys however you want, and you can define them to those used in MAME. On the other hand, if a game does not support key redefinition, you can sometimes make creative use of DOSBox's built-in keymapper. | + | You will need to carefully evaluate each of your games and decide which ones are good candidates to be included in your setup. Often times a game allows you to redefine the keys however you want, and you can define them to those used in MAME. On the other hand, if a game does not support key redefinition, you can sometimes make creative use of DOSBox's built-in keymapper (see [[#Key_Mapping]] above). |
=== Exit on ESC === | === Exit on ESC === | ||
Revision as of 14:29, 22 June 2011
The Right Way to Configure Wah!Cade for DOSBox
About
DOSBox emulates an Intel x86 PC, complete with sound, graphics, mouse, joystick, modem, etc., necessary for running many old MS-DOS games that simply cannot be run on modern PCs and operating systems, such as Microsoft Windows XP, Windows Vista, Linux and FreeBSD.
Configuration
| Platform | Version | Device | Exec | Type | commandline_format |
|---|---|---|---|---|---|
| Linux | 0.74 | Original Media | /usr/bin/dosbox | D | [rompath]/[name].[romext] -exit -conf [rompath]/conf/[name].conf |
Getting Started
Prerequisites
This guide assumes that the following apply to all of your DOS games:
- The game's files exist on your harddrive. They are either already unzipped from a ZIP archive, or extracted by an executable self-installer program.
- The game must be run from an executable file, as opposed to being self-booting.
This guide does not cover how to run games from changeable media like floppy disks or CD-ROMs.
Installing DOSBox
Visit DOSBox's download page for the most up-to-date versions of the software. Choose and download the package appropriate for your system.
On Debian-based systems like Ubuntu, simply open a Terminal and type:
sudo apt-get install dosbox
Follow the prompts and DOSBox will be downloaded and installed automatically. Test the installation by typing dosbox at the prompt. Type exit in the DOSBox window that appears to close it.
DOS Game Folder Structure
Create a main folder where you will keep all your DOS games. The example used in this guide will be named ~/dosgames.
Create the following subfolders in ~/dosgames:
- conf
- keymaps
- captures
- snaps
- movies
I'll get to the purposes of these subfolders in a bit.
Also create a subfolder for each of the DOS games you want to set up. I will use somes favorites of mine as examples:
- KEEN1
- RAPTOR
- ROUND42
- SCORCH
- XCUTE
It's important that you name your games' subfolders using only eight characters or less, because actual DOS did not support file and directory names longer than 8 characters; DOSBox behaves the same way. A good rule of thumb is to name it similar to the game's main executable file.
You'll notice that I named my game subfolders in capital letters and my non-game subfolders in lowercase letters. I use this convention for my own benefit, so I can easily differentiate those that contain game files apart from those that don't.
Now that your folder structure is set up, copy each of your game's files into its corresponding subfolder. Make a note of the main executable filename for each game.
Batch (.BAT) Files
Back in your ~/dosgames folder, create a new text file. Name it identically to one of your game's subfolder, and give it a .BAT file extension. This is a DOS batch file. Open the file and give it text like the following:
@echo off cd round42 round42.com
(Unless you've already guessed by now, replace "round42" with the folder name and executable name of one of your games.)
The batch file serves two main purposes:
- The first is to change the current working directory to the game's subfolder before running the game itself.
- The second purpose is to specify the type of file being executed. A DOS game's executable file will almost always be a .EXE file. There are some rare cases, however, particularly with older games, where the extension would be .COM. COM files are executed in the same manner as EXE files. In the batch file you can specify either type, meaning you don't have to rely on a game's extension being EXE for it to be visible in your Wah!Cade game list.
The "@echo off" statement hides the batch commands from view as they are processed in the DOSBox window. It's optional, but recommended.
Save and close the batch file. Test it:
dosbox ~/dosgames/ROUND42.BAT
If all went well, DOSBox should have executed the game. Exit the game, or force terminate using CTRL-F9 if necessary.
Repeat the batch file creation for all of your games.
DOSBox Configuration Per Game
Why Per Game?
Due to the wide diversity of games on DOS, and the longevity of DOS as a gaming platform, it's critical to maintain individual DOSBox configurations for each game. A DOS game from 1982 is going to require a vastly different DOSBox configuration than one from 1996, because computers evolved significantly in that 14-year span. This is as opposed to console emulators, where one configuration works for all games.
CONF File Creation
On DOSBox's first run, it creates a config file in ~/.dosbox named dosbox-version.conf. Copy this file to ~/dosgames/conf.
Make as many copies of this file as you have DOS games, naming each one identically to the game's subfolder name with a .conf extension (e.g.: ROUND42.conf).
Editing a CONF File
Open one of your conf files in a text editor (vim or gedit). You will see many different options to change. You'll also notice some documentation is provided for most settings.
Some common things you may want to change:
fullscreen=true fulldouble=true fullresolution=original windowresolution=original output=openglnb
You will see an option called mapperfile. Set this to a (currently) nonexistent file in your ~/dosgames/keymaps subfolder. For my ROUND42 example:
mapperfile=~/dosgames/keymaps/mapper_ROUND42.txt
Adjust your settings in each of your games' conf files, making sure you have set your mapperfile paths properly for each one. Also edit the captures option. Set it to ~/dosgames/captures. You'll see why later on.
Some older games may require different machine types in order to work properly. For example, try setting the machine option to tandy for games that ran on the Tandy 1000 line of computers.
For older games that did not use sound cards, you will need to make sure you set pcspeaker to true in order to hear the PC "beep" sound effects.
You will also see options for frameskipping, cpu type, and many others. Most of the time you can leave these as they are. DOSBox's official documentation on these options is available at this link: Dosbox.conf.
Test a game using the appropriate conf file:
dosbox ~/dosgames/ROUND42.BAT -conf ~/dosgames/conf/ROUND42.conf
Again, the game will come up. This time, using the options as you configured, like fullscreen.
Run the Games' Setup Utilities
Don't forget to run the setup/install utilities for the games that have them. Display modes (CGA, EGA, VGA), sound settings (Sound Blaster, AdLib), and controls need to be configured just as if this were actual DOS.
Execute the setup utility with DOSBox. For example:
dosbox ~/dosgames/GAMENAME/SETUP.EXE
Usually, default Sound Blaster settings work just fine. Just make sure the IRQ and DMA settings you set for the game match those defined in the corresponding conf file.
Refer to your game's README files or help docs for more info.
Key Mapping
Creating a Custom Mapper File
While in the game, press CTRL-F1 to activate the keymapper. I won't go into much detail here on how the keymapper works, but complete documentation can be found here: Mapper
Reset Mapper To Default
If you take a look in the ~/dosgames/keymaps subfolder, you'll see that a mapper file has been created. If you ever want to reset a game's keymapping, simply delete this file and a fresh one will be generated next time you activate the keymapper while in a game.
Snaps / Movies
Creating Screenshots
While playing a game in DOSBox, pressing CTRL-F5 will take a PNG screenshot and save it to the captures subfolder you specified in the game's conf file. It will be named the same as the game's name with lowercase letters and a numeric suffix.
Store screenshots in ~/dosgames/snaps. As with all platforms in Wah!Cade, the image filenames must exactly match the names of the roms. The "roms" in this case are the batch files you created.
Follow the same procedure if you want screenshots of title screens, game-over messages, high score listings, etc.
Recording Movies
While playing a game in DOSBox, pressing CTRL-ALT-F5 will begin recording an AVI movie. Pressing CTRL-ALT-F5 again will stop recording and save the resulting movie in the captures subfolder you specified in the game's conf file. It will be named the same as the game's name with a numeric suffix.
Store movies in ~/dosgames/movies. As with snaps, the movie filenames must exactly match the names of your batch files.
Adding DOSBox To Wah!Cade
In Wah!Cade Setup Editor, under the Emulators tab, add DOSBox as a platform. Set your rom path to ~/dosgames, rom extension to BAT, your commandline format to [rompath]/[name].[romext] -exit -conf [rompath]/conf/[name].conf, and your artwork 1 path to [rompath]/snaps.
Alternatively, you can edit your dosbox.ini file in ~/.wahcade/ini accordingly:
### dosbox.ini (wahcade v0.99) ### ### by codefenix ### emulator_title Dosbox v0.72 ### List Generation Settings ### rom_path ~/dosgames rom_extension BAT dat_file nms_file catver_ini_file list_generation_method rom_folder ### Execution Settings ### emulator_executable /usr/bin/dosbox commandline_format [rompath]/[name].[romext] -exit -conf [rompath]/conf/[name].conf alt_commandline_format_1 alt_commandline_format_2 game_specific_config_path ### Artwork Locations ### artwork_1_image_path [rompath]/snaps artwork_2_image_path artwork_3_image_path artwork_4_image_path artwork_5_image_path artwork_6_image_path artwork_7_image_path artwork_8_image_path artwork_9_image_path artwork_10_image_path movie_preview_path movie_artwork_no 1 ### Screen-Saver Settings ### enable_music_in_screensaver 0 saver_type slideshow movie_path movie_fullscreen 1 quit_delay 30 wrapper_executable wrapper_commandline_format [name] scr_file ### External Application Settings ### ipc_file_or_path app_1_executable app_1_commandline_format app_2_executable app_2_commandline_format app_3_executable app_3_commandline_format auto_launch_apps ### Additional Settings ### music_path lcd_display_file_path lcd_fe_text ### Settings used by MAMEWAH ### current_list 0
You'll note that the -exit parameter is used in the commandline format. This tells DOSBox to close itself after the game terminates.
If you did everything right, when you launch Wah!Cade you should be able to select DOSBox as a platform and browse the list of games. Select any game and start it, and DOSBox will use the appropriate config and keymap settings automatically. You will be returned back to Wah!Cade upon exiting the game.
Cabinet-Friendliness Tips
A game's ability to be 100% playable using MAME-like arcade controls is referred to as its cabinet-friendliness. If you're using DOSBox with Wah!Cade in an arcade cabinet, you'll soon realize that not all of your DOS games play very well using the controls, especially those that require full use of the keyboard.
You will need to carefully evaluate each of your games and decide which ones are good candidates to be included in your setup. Often times a game allows you to redefine the keys however you want, and you can define them to those used in MAME. On the other hand, if a game does not support key redefinition, you can sometimes make creative use of DOSBox's built-in keymapper (see #Key_Mapping above).
Exit on ESC
By default DOSBox can be force-terminated by pressing CTRL+F9. This is referred to as "shutdown" within DOSBox. Using the keymapper, you can remap shutdown to the ESC key for many games that don't already have a simple method of quitting.
See: Cabinet-Friendly DOS Games
Suggested Layouts
Use any of the following layouts for your DOSBox platform in Wah!Cade Layout Editor:
- DOS Layouts
Codefenix's custom layout for MS-DOS
1152 x 864
PC Games layout from the Emuchrist collection
640x480
Zombie's unofficial Emuchrist-like layout for MS-DOS
640x480
Zombie's unofficial Emuchrist-like layout for FreeDOS
640x480
External Links
- DOSBox Homepage - All things DOSBox, including a FAQ page, forum, and game compatibility listings.
- DOSBoxWiki - The official Wiki page of the DOSBox project.
- Wikipedia's article on DOSBox - For everything else.
- Cabinet-Friendly DOSBox Games thread at anti-particle.com - A work-in-progress listing of cabinet-friendly DOS games.