Difference between revisions of "Emulator:DOSBox"

From Wah!ki
Jump to navigation Jump to search
(Reworded some verbose sections, removed first-person narrative, removed extra spaces from code indents.)
Line 24: Line 24:
 
=== Prerequisites ===
 
=== Prerequisites ===
 
This guide assumes that the following apply to all of your DOS games:
 
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's files exist on your harddrive.  They are either already unzipped from a ZIP archive or extracted via an executable self-installer program.
 
* The game must be run from an executable file, as opposed to being self-booting.
 
* The game must be run from an executable file, as opposed to being self-booting.
  
Line 33: Line 33:
  
 
On Debian-based systems like Ubuntu, simply open a Terminal and type:
 
On Debian-based systems like Ubuntu, simply open a Terminal and type:
−
  sudo apt-get install dosbox
+
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.
 
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 ==
 
== 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 a main folder where all your DOS games will be kept.  The example used in this guide will be named '''~/dosgames'''.
  
 
Create the following subfolders in ~/dosgames:
 
Create the following subfolders in ~/dosgames:
Line 48: Line 48:
 
* '''movies'''
 
* '''movies'''
  
−
I'll get to the purposes of these subfolders in a bit.   
+
The purpose of each subfolder is explained later in this guide.   
  
−
Also create a subfolder for each of the DOS games you want to set up.  I will use somes favorites of mine as examples:
+
Each DOS game will be kept in its own subfolder.  Examples are provided below:
  
 
* '''KEEN1'''
 
* '''KEEN1'''
Line 58: Line 58:
 
* '''XCUTE'''
 
* '''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.
+
It is important to name the games' subfolders using only eight characters or less, because actual DOS does 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.
+
Note that in this guide the game subfolders are named using capital letters and the non-game subfolders are named in lowercase letters.  This convention is handy for differentiating those that contain game files apart from those that do not.
−
 
 
−
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 ==
 
== 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:
+
In the '''~/dosgames''' folder, create a new text file.  Name it identically to a game's subfolder, and give it a '''.BAT''' file extension.  This is a [http://en.wikipedia.org/wiki/Batch_file DOS batch file].  The batch file will perform two basic tasks:
 +
* Change the current working directory to the game's subfolder.
 +
* Run the executable, which may be either an [http://en.wikipedia.org/wiki/EXE EXE] file or, particularly with older games, a [http://en.wikipedia.org/wiki/COM_file COM] file.
  
−
  @echo off
+
This example batch file changes to the directory in which the game ROUND42 is located, and then runs it:
−
  cd round42
+
@echo off
−
  round42.com
+
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 "@echo off" statement hides the batch commands from view as they are processed in the DOSBox window.  It is optional, but recommended.
  
−
The batch file serves two main purposes:
+
Save and close the batch file.  Test it in a terminal:
−
* The first is to change the current working directory to the game's subfolder before running the game itself.
+
dosbox ~/dosgames/ROUND42.BAT
−
* 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 run the game.  Exit the game, or force terminate using CTRL-F9 if necessary.
 
If all went well, DOSBox should run the game.  Exit the game, or force terminate using CTRL-F9 if necessary.
  
−
Repeat the batch file creation for all of your games.
+
Repeat this batch file creation for all games.
  
 
== DOSBox Configuration Per Game==
 
== DOSBox Configuration Per Game==
 
=== Why 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.  While one console emulator configuration works the same for all game on the system because the hardware remained unchanged, 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.   
+
It is important to maintain individual DOSBox configurations for each game due to the wide diversity of games on DOS, and the longevity of DOS as a gaming platform.  While a given console emulator configuration works identically for all games on the system because the hardware remained unchanged from game to 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.   
  
 
=== CONF File Creation ===
 
=== CONF File Creation ===
 
On DOSBox's first run, it creates a config file in '''~/.dosbox''' named '''dosbox.conf'''.  The filename may contain a version number on Linux.  Copy this file to '''~/dosgames/conf'''.
 
On DOSBox's first run, it creates a config file in '''~/.dosbox''' named '''dosbox.conf'''.  The filename may contain a version number on Linux.  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 there are DOS games, naming each one identically to the game's subfolder name with a '''.conf''' extension (e.g.: ROUND42.conf).
  
 
=== Editing a CONF File ===
 
=== 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.
+
Open one a conf file in a text editor.  The following are common things to change:
−
 
 
−
Some common things you may want to change:
 
  
−
  fullscreen=true
+
fullscreen=true
−
  fulldouble=true
+
fulldouble=true
−
  fullresolution=original
+
fullresolution=original
−
  windowresolution=original
+
windowresolution=original
−
  output=openglnb
+
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:
+
There is an option called '''mapperfile'''.  This should be set to a (currently) nonexistent file in the '''~/dosgames/keymaps''' subfolder.  Following the ROUND42 example:
  
−
  mapperfile=~/dosgames/keymaps/mapper_ROUND42.txt  
+
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.
+
Adjust settings in each games' conf file, making sure to set the mapperfile paths properly for each one.  Also edit the '''captures''' option.  Set it to '''~/dosgames/captures'''.  This is explained 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, the '''machine''' option must be set 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.
+
For older games that did not use sound cards, '''pcspeaker''' should be set to '''true''' in order to emulate PC "beep" sound effects through the system sound card.
  
−
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].
+
There are also options for frameskipping, cpu type, and many others.  Usually these can be left as they are.  DOSBox's official documentation on these options is available at this link: [http://www.dosbox.com/wiki/Dosbox.conf Dosbox.conf].
  
 
Test a game using the appropriate conf file:
 
Test a game using the appropriate conf file:
 +
dosbox ~/dosgames/ROUND42.BAT -conf ~/dosgames/conf/ROUND42.conf
  
−
  dosbox ~/dosgames/ROUND42.BAT -conf ~/dosgames/conf/ROUND42.conf
+
Again, the game will come up.  This time, using the defined configuration.  If fullscreen was set to true, the game will fill the entire window.
−
 
 
−
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), sound settings (Sound Blaster, AdLib), and controls need to be configured just as if this were actual DOS.
+
It is important 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.  In a terminal window:
 +
dosbox ~/dosgames/GAMENAME/SETUP.EXE
  
−
  dosbox ~/dosgames/GAMENAME/SETUP.EXE
+
Usually, default Sound Blaster settings work just fine.  If necessary, match the IRQ and DMA settings to those defined in the corresponding conf file.
  
−
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 the game's README files or help docs for more info.
−
 
 
−
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.  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]
+
While playing a game in DOSBox, press CTRL-F1 to activate the keymapper.  Complete documentation on the keymapper can be found here: [http://www.dosbox.com/wiki/Keymapper Mapper].  Upon exiting the keymapper, a keymap file for the game is save in the '''~/dosgames/keymaps''' subfolder.  To reset a game's keymapping, simply delete this file.  A new one will be generated the next time the keymapper is activated while playing the game.
−
 
 
−
=== 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 ==
 
== Snaps / Movies ==
 
=== Creating Screenshots ===
 
=== 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.
+
While playing a game in DOSBox, press CTRL-F5 to take a PNG screenshot, and it will be saved to the '''captures''' subfolder specified in the game's conf file.  It will be named the same as the game's name in lowercase letters with 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.
+
Screenshots should be stored in '''~/dosgames/snaps'''.  As with all platforms in Wah!Cade, image filenames must exactly match the names of roms.  The "roms" in this case are the batch files created.
  
−
Follow the same procedure if you want screenshots of title screens, game-over messages, high score listings, etc.
+
Follow the same procedure to make screenshots of title screens, game-over messages, high score listings, etc.
  
 
=== Recording Movies ===
 
=== 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.
+
While playing a game in DOSBox, press CTRL-ALT-F5 to begin recording an AVI movie.  Press CTRL-ALT-F5 again to stop recording, and the resulting movie will be saved in the '''captures''' subfolder 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.
+
Movies should be stored in '''~/dosgames/movies'''.  As with snaps, the movie filenames must exactly match the names of the 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 '''~/dosgames''', rom extension to '''BAT''', your commandline format to '''"[rompath]/[name].[romext]" -exit -conf "[rompath]/conf/[name].conf"''', and your artwork 1 path to your snaps folder.
+
In '''Wah!Cade Setup Editor''', under the '''Emulators''' tab, add DOSBox as a platform.  Set the rom path to '''~/dosgames''', rom extension to '''BAT''', commandline format to '''"[rompath]/[name].[romext]" -exit -conf "[rompath]/conf/[name].conf"''', and the artwork 1 path to the snaps folder.
  
−
Alternatively, you can edit your '''dosbox.ini''' file in '''~/.wahcade/ini''' accordingly:
+
Alternatively, edit the '''dosbox.ini''' file in '''~/.wahcade/ini''' accordingly:
−
 
+
### dosbox.ini (wahcade v0.99) ###
−
  ### dosbox.ini (wahcade v0.99) ###
+
### by codefenix ###
−
  ### by codefenix ###
+
−
 
+
emulator_title                          DOSBox
−
  emulator_title                          DOSBox
+
−
 
+
### List Generation Settings ###
−
  ### List Generation Settings ###
+
rom_path                                ~/dosgames
−
  rom_path                                ~/dosgames
+
rom_extension                          BAT
−
  rom_extension                          BAT
+
dat_file                                 
−
  dat_file                                 
+
nms_file                                 
−
  nms_file                                 
+
catver_ini_file                         
−
  catver_ini_file                         
+
list_generation_method                  rom_folder
−
  list_generation_method                  rom_folder
+
−
 
+
### Execution Settings ###
−
  ### Execution Settings ###
+
emulator_executable                    /usr/bin/dosbox
−
  emulator_executable                    /usr/bin/dosbox
+
commandline_format                      "[rompath]/[name].[romext]" -exit -conf "[rompath]/conf/[name].conf"
−
  commandline_format                      "[rompath]/[name].[romext]" -exit -conf "[rompath]/conf/[name].conf"
+
alt_commandline_format_1                 
−
  alt_commandline_format_1                 
+
alt_commandline_format_2                 
−
  alt_commandline_format_2                 
+
game_specific_config_path               
−
  game_specific_config_path               
 
−
 
 
−
  ### Artwork Locations ###
 
−
  artwork_1_image_path                   
 
−
  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 ###
+
### Artwork Locations ###
−
  current_list                            0
+
artwork_1_image_path                   
 +
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.  
+
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.
+
Launch Wah!Cade, 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.  Control is returned back to Wah!Cade upon exiting the game.
  
 
== Cabinet-Friendliness Tips ==
 
== 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.   
+
A game's ability to be 100% playable using MAME-like arcade controls is referred to as its [[cabinet-friendliness]].  Not all DOS games play very well using these controls, as many require full use of the keyboard.  Sometimes a game's keys may be redefined to match those used in MAME.  However, if a game does not support key redefinition, it then becomes necessary to make creative use of DOSBox's built-in keymapper (see [[#Key_Mapping]] above).  
−
 
 
−
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).  
 
  
 
''See: [[Cabinet-Friendly DOS Games]]''
 
''See: [[Cabinet-Friendly DOS Games]]''
  
 
=== Exit on ESC ===
 
=== Exit on ESC ===
−
By default DOSBox can be force-terminated by pressing CTRL+F9.  This is called "shutdown".  Using the keymapper, you can remap shutdown to the ESC key for many games that don't already have a simple method of quitting.
+
By default DOSBox can be force-terminated by pressing CTRL+F9.  This is called "shutdown".  Using the keymapper, remap shutdown to the ESC key for games that do not already have a simple method of quitting.
  
 
== Suggested Layouts ==
 
== Suggested Layouts ==
−
Use any of the following layouts for your DOSBox platform in Wah!Cade Layout Editor:
 
−
 
 
<gallery caption="DOS Layouts">
 
<gallery caption="DOS Layouts">
−
File:Dos layout 1152x864.jpg|Codefenix's custom layout for MS-DOS<br />[http://www.mameau.com/wiki/images/9/94/Dos_layout_1152x864.jpg 1152 x 864]
 
 
File:Classic-bw-640x480-pcgames.jpg|PC Games layout from the Emuchrist collection<br />[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_bw_640x480/pcgames_bw.zip 640x480]
 
File:Classic-bw-640x480-pcgames.jpg|PC Games layout from the Emuchrist collection<br />[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_bw_640x480/pcgames_bw.zip 640x480]
 
File:Pcgames-main.jpg|PC Games layout from the Emuchrist collection<br />[[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_640x480/pcgames_c.zip 640x480]]<br />[[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_800x600/pcgames_c.zip 800x600]]
 
File:Pcgames-main.jpg|PC Games layout from the Emuchrist collection<br />[[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_640x480/pcgames_c.zip 640x480]]<br />[[http://{{SERVERNAME}}/files/layouts/emuchrist/classic_800x600/pcgames_c.zip 800x600]]
 
File:Cpviewer-dosgames-unofficial.jpg|Zombie's unofficial Emuchrist-like layout for MS-DOS<br />[http://{{SERVERNAME}}/files/layouts/unofficial/cpviewer/dosgames_bw.zip 640x480]
 
File:Cpviewer-dosgames-unofficial.jpg|Zombie's unofficial Emuchrist-like layout for MS-DOS<br />[http://{{SERVERNAME}}/files/layouts/unofficial/cpviewer/dosgames_bw.zip 640x480]
 
File:Cpviewer-freedos-unofficial.jpg|Zombie's unofficial Emuchrist-like layout for FreeDOS<br />[http://{{SERVERNAME}}/files/layouts/unofficial/cpviewer/freedos_bw.zip 640x480]
 
File:Cpviewer-freedos-unofficial.jpg|Zombie's unofficial Emuchrist-like layout for FreeDOS<br />[http://{{SERVERNAME}}/files/layouts/unofficial/cpviewer/freedos_bw.zip 640x480]
 +
File:Dos layout 1152x864.jpg|Codefenix's custom layout for MS-DOS<br />[http://www.mameau.com/wiki/images/9/94/Dos_layout_1152x864.jpg 1152 x 864]
 
</gallery>
 
</gallery>
  

Revision as of 16:41, 19 December 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 via 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 all your DOS games will be kept. The example used in this guide will be named ~/dosgames.

Create the following subfolders in ~/dosgames:

  • conf
  • keymaps
  • captures
  • snaps
  • movies

The purpose of each subfolder is explained later in this guide.

Each DOS game will be kept in its own subfolder. Examples are provided below:

  • KEEN1
  • RAPTOR
  • ROUND42
  • SCORCH
  • XCUTE

It is important to name the games' subfolders using only eight characters or less, because actual DOS does 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.

Note that in this guide the game subfolders are named using capital letters and the non-game subfolders are named in lowercase letters. This convention is handy for differentiating those that contain game files apart from those that do not.

Batch (.BAT) Files

In the ~/dosgames folder, create a new text file. Name it identically to a game's subfolder, and give it a .BAT file extension. This is a DOS batch file. The batch file will perform two basic tasks:

  • Change the current working directory to the game's subfolder.
  • Run the executable, which may be either an EXE file or, particularly with older games, a COM file.

This example batch file changes to the directory in which the game ROUND42 is located, and then runs it: 

@echo off
cd round42
round42.com

The "@echo off" statement hides the batch commands from view as they are processed in the DOSBox window. It is optional, but recommended.

Save and close the batch file. Test it in a terminal: 

dosbox ~/dosgames/ROUND42.BAT

If all went well, DOSBox should run the game. Exit the game, or force terminate using CTRL-F9 if necessary.

Repeat this batch file creation for all games.

DOSBox Configuration Per Game

Why Per Game?

It is important to maintain individual DOSBox configurations for each game due to the wide diversity of games on DOS, and the longevity of DOS as a gaming platform. While a given console emulator configuration works identically for all games on the system because the hardware remained unchanged from game to 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.

CONF File Creation

On DOSBox's first run, it creates a config file in ~/.dosbox named dosbox.conf. The filename may contain a version number on Linux. Copy this file to ~/dosgames/conf.

Make as many copies of this file as there are 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 a conf file in a text editor. The following are common things to change: 

fullscreen=true
fulldouble=true
fullresolution=original
windowresolution=original
output=openglnb

There is an option called mapperfile. This should be set to a (currently) nonexistent file in the ~/dosgames/keymaps subfolder. Following the ROUND42 example: 

mapperfile=~/dosgames/keymaps/mapper_ROUND42.txt

Adjust settings in each games' conf file, making sure to set the mapperfile paths properly for each one. Also edit the captures option. Set it to ~/dosgames/captures. This is explained later on.

Some older games may require different machine types in order to work properly. For example, the machine option must be set to tandy for games that ran on the Tandy 1000 line of computers.

For older games that did not use sound cards, pcspeaker should be set to true in order to emulate PC "beep" sound effects through the system sound card.

There are also options for frameskipping, cpu type, and many others. Usually these can be left 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 defined configuration. If fullscreen was set to true, the game will fill the entire window.

Run the Games' Setup Utilities

It is important 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. In a terminal window: 

dosbox ~/dosgames/GAMENAME/SETUP.EXE

Usually, default Sound Blaster settings work just fine. If necessary, match the IRQ and DMA settings to those defined in the corresponding conf file.

Refer to the game's README files or help docs for more info.

Key Mapping

Creating a Custom Mapper File

While playing a game in DOSBox, press CTRL-F1 to activate the keymapper. Complete documentation on the keymapper can be found here: Mapper. Upon exiting the keymapper, a keymap file for the game is save in the ~/dosgames/keymaps subfolder. To reset a game's keymapping, simply delete this file. A new one will be generated the next time the keymapper is activated while playing the game.

Snaps / Movies

Creating Screenshots

While playing a game in DOSBox, press CTRL-F5 to take a PNG screenshot, and it will be saved to the captures subfolder specified in the game's conf file. It will be named the same as the game's name in lowercase letters with a numeric suffix.

Screenshots should be stored in ~/dosgames/snaps. As with all platforms in Wah!Cade, image filenames must exactly match the names of roms. The "roms" in this case are the batch files created.

Follow the same procedure to make screenshots of title screens, game-over messages, high score listings, etc.

Recording Movies

While playing a game in DOSBox, press CTRL-ALT-F5 to begin recording an AVI movie. Press CTRL-ALT-F5 again to stop recording, and the resulting movie will be saved in the captures subfolder specified in the game's conf file. It will be named the same as the game's name with a numeric suffix.

Movies should be stored in ~/dosgames/movies. As with snaps, the movie filenames must exactly match the names of the batch files.

Adding DOSBox To Wah!Cade

In Wah!Cade Setup Editor, under the Emulators tab, add DOSBox as a platform. Set the rom path to ~/dosgames, rom extension to BAT, commandline format to "[rompath]/[name].[romext]" -exit -conf "[rompath]/conf/[name].conf", and the artwork 1 path to the snaps folder.

Alternatively, edit the dosbox.ini file in ~/.wahcade/ini accordingly: 

### dosbox.ini (wahcade v0.99) ###
### by codefenix ###

emulator_title                          DOSBox

### 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                    
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

Note that the -exit parameter is used in the commandline format. This tells DOSBox to close itself after the game terminates.

Launch Wah!Cade, 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. Control is 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. Not all DOS games play very well using these controls, as many require full use of the keyboard. Sometimes a game's keys may be redefined to match those used in MAME. However, if a game does not support key redefinition, it then becomes necessary to make creative use of DOSBox's built-in keymapper (see #Key_Mapping above).

See: Cabinet-Friendly DOS Games

Exit on ESC

By default DOSBox can be force-terminated by pressing CTRL+F9. This is called "shutdown". Using the keymapper, remap shutdown to the ESC key for games that do not already have a simple method of quitting.

Suggested Layouts

  • DOS Layouts

  • PC Games layout from the Emuchrist collection
    640x480

  • PC Games layout from the Emuchrist collection
    [640x480]
    [800x600]

  • Zombie's unofficial Emuchrist-like layout for MS-DOS
    640x480

  • Zombie's unofficial Emuchrist-like layout for FreeDOS
    640x480

  • Codefenix's custom layout for MS-DOS
    1152 x 864

External Links

Retrieved from "https://wahki.mameau.com/index.php?title=Emulator:DOSBox&oldid=2477"