# DOSBox configuration file parameters

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

1. Browse the gamebox contents 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:

- You must switch to the program’s directory first, or else specify the full DOS path to the program: e.g. `C:\MYGAME\MYTSR.COM`.
- You must run .bat batch files via the `CALL` command: e.g. `CALL C:\MYGAME\MYBAT.BAT`.
- Boxer will launch the gamebox’s default program itself once all autoexec commands have run.

## Endnote for experienced DOSBox users

- This page lists only those settings that you may need to change in order to get a game to work in Boxer. Most DOSBox settings should be left at their defaults, and these are not listed above.

- This page also omits DOSBox settings that are no longer supported by Boxer and thus have no effect. This includes the entire `[sdl]` section, along with settings like `aspect`, `scaler` and `capture`.

- Boxer automatically configures hundreds of games that would otherwise require custom DOSBox settings. Make sure the game does not work out-of-the-box before changing the emulation settings, and only add the settings you know are needed.

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.