DOSBox configuration file parameters

The parameters below control advanced features of the DOS emulation. If needed, they can be added to your game’s configuration file:

  1. Show the contents of the game’s gamebox in Finder.
  2. Double-click on the DOSBox Preferences.conf file inside to open it in TextEdit.
  3. Paste in the setting you need, ensuring that you include the [section] tag with the setting.

Boxer’s goal is zero configuration: if a game won’t work in Boxer without custom configuration settings, then send me the game’s details so Boxer can configure that game automatically in future.

Emulated machine types

[dosbox]
machine=(mode)

The type of computer and video-card to emulate. Modes include:

[dosbox]
machine=svga_s3
The default: S3 Trio64 SuperVGA card with 2MB of video memory.
The most capable mode, and suitable for almost all games.
[dosbox]
machine=vgaonly
VGA card without SuperVGA support. Needed for some games that are incompatible with SVGA or use VGA-specific tricks.
[dosbox]
machine=ega
16-colour EGA graphics adapter.
[dosbox]
machine=tandy
Emulates a Tandy 1000 with 3-voice sound.
Tandy sound emulation is only available in this mode.
[dosbox]
machine=pcjr
Emulates an IBM PCjr.
[dosbox]
machine=cga
4-colour CGA graphics adapter. Provides support for CGA-specific graphical tricks used by some games.
[dosbox]
machine=hercules
Hercules monochrome graphics adapter.

The following alternate SVGA modes are also available:

[dosbox]
machine=svga_et4000
Tseng ET-4000 SuperVGA card with 1MB of memory.
[dosbox]
machine=svga_et3000
Tseng ET-3000 SuperVGA card with 512kB of memory.
[dosbox]
machine=svga_paradise
Paradise PVGA1A SuperVGA card with 512kB of memory.
[dosbox]
machine=vesa_oldvbe
Same as machine=svga_s3, with an older VESA 1.2 BIOS instead of VESA 2.0.
[dosbox]
machine=vesa_nolfb
Same as machine=svga_s3, with linear frame buffer modes disabled.

Memory emulation

[dosbox]
memsize=(0–63)

The amount of extended and expanded memory available, in MB. (This does not include the initial 1MB of conventional and upper memory.)

[dosbox]
memsize=16
The default: emulates 16MB of extended/expanded memory, for 17MB total. Recommended for all games: no DOS game needs more than this, and very few can take advantage of memory beyond 16MB.
[dosbox]
memsize=31
Emulates 31MB of extended/expanded memory, for 32MB total.
May improve performance in very demanding late-era DOS games.
[dosbox]
memsize=63
The maximum supported amount of memory. Not recommended.

[dos]
ems=(true/false)
xms=(true/false)
umb=(true/false)

Expanded memory (“EMS”), extended memory (“XMS”), and upper memory (“UMB”) are all emulated by default. These can be selectively disabled for games that don’t support them.

[dos]
ems=false
Disables expanded memory emulation.
[dos]
xms=false
Disables extended memory emulation.
[dos]
upper=false
Disables upper memory emulation.

CPU emulation

The recommended way to adjust CPU settings is from Boxer’s CPU Inspector, opened by pressing Cmd ⌘+I while playing. This panel provides easier access to common CPU tweaks.

[cpu]
core=(mode)

Which CPU emulation technique to use. Modes include:

[cpu]
core=auto
The default. Switches automatically between core=normal for older real-mode games, and core=dynamic for newer protected-mode games.
[cpu]
core=dynamic
Provides the best performance, but is incompatible with some games and unavailable on PowerPC Macs.
Equivalent to enabling “Optimize for newer games” in the CPU Inspector.
[cpu]
core=normal
Runs slower than dynamic core, especially for more demanding games, but is more accurate and stable.
Equivalent to disabling “Optimize for newer games” in the CPU Inspector.
[cpu]
core=simple
Similar to core=normal but optimized for older real-mode games.

[cpu]
cycles=(fixed 1-99999/max)

The emulated CPU speed, expressed as “cycles” or CPU instructions per millisecond. Some examples:

[cpu]
cycles=fixed 1000
Emulates 1000 CPU instructions per millisecond, giving a similar speed to an 80286 AT.
[cpu]
cycles=max
Emulates the CPU as fast as your Mac can manage. Equivalent to dragging the speed slider to Max on Boxer’s CPU Inspector Panel.
[cpu]
cycles=max limit 50000
Emulates the CPU as fast as your Mac can manage, up to a maximum of 50,000 instructions per millisecond.
[cpu]
cycles=auto
The default. Emulates at 3000 instructions per millisecond for older real-mode games, switching to maximum speed for newer protected-mode games.

See the DOSBox Wiki for more complex examples for this parameter.

[cpu]
cputype=(type)

The kind of CPU to emulate and identify as. Types include:

[cpu]
cputype=auto
The default. Identifies as a 486DX CPU, with emulation behaviour optimized for compatibility and speed. Always use this unless you know the game needs a different setting.
[cpu]
cputype=386
Supports 386 features only, with optimized page privilege checks.
[cpu]
cputype=386_slow
Same as cputype=386, but with slower strict page privilege checks.
[cpu]
cputype=386_prefetch
core=normal
Same as cputype=386, but with optimized prefetch queue emulation.
Requires core=normal.
[cpu]
cputype=486_slow
Identifies as a 486DX, with 486-specific behaviour and slower strict page privilege checks.
[cpu]
cputype=pentium_slow
Identifies as a Pentium CPU with Pentium-specific behaviour.
Needed for Windows 95, and for some games that run CPU performance checks.

Sound card emulation

[midi]
mididevice=(device)

How Boxer will play back MIDI music. Devices include:

[midi]
mididevice=default
The default. Automatically selects the best device for the music being played: coreaudio for General MIDI music, and mt32 for MT-32 music.
[midi]
mididevice=coreaudio
Plays MIDI music through OS X’s built-in General MIDI synth.
[midi]
mididevice=mt32
Plays MIDI music through a real MT-32 device (if one is connected to your Mac) or through Boxer’s MT-32 emulation (if MT-32 ROMs are available.)
[midi]
mididevice=coremidi
midiconfig=0

Sends MIDI music to a physical MIDI device connected to your Mac.

midiconfig determines which MIDI device Boxer should talk to. This should be 0, unless you have multiple devices connected.

[midi]
mpu401=(mode)

The MIDI interface mode to emulate.

[midi]
mpu401=intelligent
The default. Emulates the full MPU-401 MIDI interface.
[midi]
mpu401=uart
Handles only the MIDI signal relaying needed by games, disabling additional MPU-401 features.
[midi]
mpu401=none
Disables MIDI emulation entirely.

[sblaster]
sbtype=(type)
irq=(5/7)

Controls Sound Blaster emulation. Settings include:

[sblaster]
sbtype=sb16
sbbase=220
irq=7
dma=1
hdma=5

The default settings. Emulates a Sound Blaster 16, which works for almost all Sound Blaster-compatible games.

You may need irq=5 instead, if the game has been pre-configured for a different IRQ. All other settings should be left at their defaults.

[sblaster]
sbtype=sbpro2
Sound Blaster Pro 2.0: stereo, 8-bit digital audio and OPL-3 synthesis.
[sblaster]
sbtype=sbpro1
Sound Blaster Pro 1.0: same as above but older OPL-2 synthesis.
[sblaster]
sbtype=sb2
Sound Blaster 2.0: mono, 8-bit digital audio and OPL-2 synthesis.
[sblaster]
sbtype=sb1
Sound Blaster 1.0: same as above, but worse sample rate and synthesis.
[sblaster]
sbtype=gb
CMS Game Blaster: the precursor to the Sound Blaster, with worse sound and no AdLib compatibility.
[sblaster]
sbtype=none
Disables Sound Blaster emulation entirely.

Additional settings:

[sblaster]
sbmixer=false
Prevents games from modifying the Sound Blaster’s volume.
Useful for games that otherwise play digital sound too softly in relation to their MIDI music.

[gus]
gus=(true/false)
ultradir=(path)

Controls Gravis Ultrasound emulation. Settings include:

[gus]
gus=true
gusbase=240
gusirq=5
gusdma=3

The default. Emulates the Gravis Ultrasound with standard factory settings.

[gus]
gus=false
Disables Gravis Ultrasound emulation.
Needed for games that autodetect the Gravis Ultrasound but are incompatible with the emulation.

For playing music the Gravis Ultrasound relies on sets of instrument sample files, which must be located within the DOS filesystem.

Boxer includes the original Gravis Ultrasound sample set, but you can add a custom set into your gamebox’s C drive and use them via:

[gus]
ultradir=C:\ULTRASND

Tells the Gravis Ultrasound to look in the C:\ULTRASND folder inside the gamebox for instrument samples.

(The default is Y:\ULTRASND, which contains Boxer’s sample set.)

[speaker]
pcspeaker=(true/false)
disney=(true/false)

The PC speaker and Disney Sound Source (also known as the “Covox Speech Thing”) are enabled by default but can be selectively disabled.

[speaker]
pcspeaker=false
Disables PC speaker sound.
[speaker]
disney=false
Disables Disney Sound Source emulation.

[joystick]
joysticktype=(auto/2axis)
timed=(true/false)

The recommended way to adjust joystick settings is from Boxer’s Joystick Inspector, opened by pressing Cmd ⌘+I while playing. The configuration settings below control low-level aspects of the gameport emulation, and do not affect the type of joystick being emulated.

[joystick]
joysticktype=2axis
Forces Boxer to emulate joysticks with only 2 axes and 2 buttons. Needed for some older games that have problems with advanced 4-axis/4-button joysticks.
[joystick]
timed=true
Enables an alternative gameport timing method, useful if the joystick otherwise drifts or behaves erratically in-game. Equivalent to enabling “Use strict gameport timing” in the Joystick Inspector.

Autoexec commands

The following commands can be added to the [autoexec] section of the configuration file to run at startup:

[autoexec]
univbe
Installs the UniVBE VESA driver. This helps some early SVGA games that have VESA incompatibilities.
[autoexec]
loadfix -64
“Eats” 64kB of conventional memory, or however many kB you specify. Needed for games that fail to run if there is too much conventional memory.
[autoexec]
network
Opens the IPX network connection menu at startup for starting/joining multiplayer games.

You can also run other programs at startup from the [autoexec] section. Note that:

Endnote for experienced DOSBox users

If you find a game that needs custom settings, please send me the game’s details so Boxer can configure that game automatically in future. That way, the next person won’t have to wade through all these miserable configuration parameters just to play the game they love.