General

This chapter covers general emulator settings from the [dosbox] and [sdl] configuration sections - what type of machine to emulate, the amount of memory, and various general emulator options.

The machine setting selects which video adapter to emulate. The default svga_s3 (an S3 Trio64 SVGA card) covers the widest range of games. You'll only need to change it for titles that specifically require CGA, EGA, Tandy, or Hercules graphics. See Graphics adapters for a detailed overview of each adapter, or the Tutorials guide for a practical walkthrough.

The default 16 MB of RAM set via memsize is more than enough for nearly all DOS software. A few late DOS-era games need 32 MB, but these are rare exceptions.

General behavior

When you switch away from dosbox-automation (e.g., by pressing Alt+Tab), the emulator keeps running in the background by default - sound and all. If you'd rather not hear game music while you're doing something else, mute_when_inactive silences the audio output whenever the window loses focus. pause_when_inactive goes a step further and pauses the entire emulation, which is useful for games that don't have a built-in pause function.

The screensaver setting controls whether the OS screensaver is allowed to activate while DOSBox is running. By default, it's blocked to prevent the screensaver from kicking in during a long cutscene or a game that doesn't require constant input.

VESA and VGA options

The vesa_modes setting controls which VESA video modes are available beyond the standard VGA modes. The default compatible setting provides the safest set of modes - it excludes 320x200 high color modes (which weren't properly supported until the late 1990s) and certain 256-color linear framebuffer modes that cause timing problems in Build Engine games (Duke Nukem 3D, Shadow Warrior, Blood). The all setting adds these extra modes and is sometimes needed by late 1990s demoscene productions. Use halfline only for Extreme Assault, which requires a special halfline VESA mode. See vesa_modes for the full resolution table.

VGA text mode normally uses 9-pixel-wide character cells. vga_8dot_font forces 8-pixel-wide characters instead. Very few programs need this.

vga_render_per_scanline is enabled by default and emulates accurate per-scanline VGA rendering. A few games crash at startup with it enabled (Deus, Ishar 3, Robinson's Requiem, Time Warriors) - disable it on a per-game basis for those titles.

Video memory delay

The vmem_delay setting emulates the CPU-throttling effect of accessing slow video memory via the ISA bus on old video cards. This can fix flashing graphics and speed issues in Hercules, CGA, EGA, and early VGA games.

Enable it only on a per-game basis as it slows down emulation. The following games benefit from vmem_delay = on:

Configuration settings

You can set the general system parameters in the [dosbox] configuration section.

General behavior

The settings below are configured in the [sdl] section.

mute_when_inactive

Mute the sound when the window is inactive.

Possible values: on, off (default)

pause_when_inactive

Pause emulation when the window is inactive.

Possible values: on, off (default)

screensaver

Use allow or block to override the SDL_VIDEO_ALLOW_SCREENSAVER environment variable which usually blocks the OS screensaver while the emulator is running.

Possible values: auto (default), allow, block

Video adapter

machine

Set the video adapter or machine to emulate.

Possible values:

vmemsize

Video memory in MB (1--8) or KB (256 to 8192). See the machine setting for the list of valid options and defaults per adapter.

Possible values: auto (default) (uses the default for the selected video adapter), or a specific size in MB or KB.

vesa_modes

Controls which VESA video modes are available.

Possible values:

• compatible (default) -- Only the most compatible VESA modes for the configured video memory size. Recommended with 4 or 8 MB of video memory (vmemsize) for the widest compatibility with games. 320x200 high color modes are excluded as they were not properly supported until the late '90s. The 256-color linear framebuffer 320x240, 400x300, and 512x384 modes are also excluded as they cause timing problems in Build Engine games.

• halfline -- Same as compatible, but the 120h VESA mode is replaced with a special halfline mode used by Extreme Assault. Use only if needed.

• all -- All modes are available, including extra DOSBox-specific VESA modes. Use 8 MB of video memory for the best results. Some games misbehave in the presence of certain VESA modes; try compatible mode if this happens. The 320x200 high color modes available in this mode are often required by late '90s demoscene productions.

The following table shows the available resolutions in compatible mode and the minimum video memory required for each color depth. Standard VGA modes (320×200, 640×480, etc.) are always available regardless of the vesa_modes setting.

The all mode adds the following on top of compatible:

vga_8dot_font

Use 8-pixel-wide fonts on VGA adapters.

Possible values: on, off (default)

vga_render_per_scanline

Emulate accurate per-scanline VGA rendering. Currently, you need to disable this for a few games, otherwise they will crash at startup (e.g., Deus, Ishar 3, Robinson's Requiem, Time Warriors).

Possible values: on (default), off

vmem_delay

Set video memory access delay emulation.

Possible values:

• off (default) -- Disable video memory access delay emulation. This is preferable for most games to avoid slowdowns.
• on -- Enable video memory access delay emulation (3000 ns). This can help reduce or eliminate flicker in Hercules, CGA, EGA, and early VGA games.
• <number> -- Set access delay in nanoseconds. Valid range is 0 to 20000 ns; 500 to 5000 ns is the most useful range.

Memory

memsize

Amount of memory the emulated machine has in MB (16 by default). Best leave at the default setting to avoid problems with some games, though a few games might require a higher value. There is generally no speed advantage when raising this value.

Disk speed

floppy_disk_speed

Set the emulated floppy disk speed.

Possible values:

hard_disk_speed

Set the emulated hard disk speed.

Possible values:

DOS & shell

autoexec_section

How autoexec sections are handled from multiple config files.

Possible values:

automount

Mount drives/[c] directories as drives on startup, where [c] is a lower-case drive letter from a to y. The drives folder can be provided relative to the current directory or via built-in resources. Mount settings can be optionally provided using a [c].conf file alongside the drive's directory.

Possible values: on (default), off

startup_verbosity

Controls verbosity prior to displaying the program.

Possible values:

shell_config_shortcuts

Allow shortcuts for simpler configuration management. E.g., instead of config -set sbtype sb16, it is enough to execute sbtype sb16, and instead of config -get sbtype, you can just execute the sbtype command.

Possible values: on (default), off

allow_write_protected_files

Many games open all their files with writable permissions; even files that they never modify. This setting lets you write-protect those files while still allowing the game to read them. A second use-case: if you're using a copy-on-write or network-based filesystem, this setting avoids triggering write operations for these write-protected files.

Possible values: on (default), off

mcb_fault_strategy

How software-corrupted memory chain blocks should be handled.

Possible values: