Skip to content

General¶

The [dosbox] section contains the core system settings — 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 Getting Started 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.

The language setting controls the language of DOSBox Staging’s own user interface messages.

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.

Video adapter¶

machine¶

Set the video adapter or machine to emulate.

Possible values:

  • hercules – Hercules Graphics Card (HGC) (see monochrome_palette).
  • cga_mono – CGA adapter connected to a monochrome monitor (see monochrome_palette).
  • cga – IBM Color Graphics Adapter (CGA). Also enables composite video emulation (see Composite video).
  • pcjr – An IBM PCjr machine. Also enables PCjr sound and composite video emulation.
  • tandy – A Tandy 1000 machine with TGA graphics. Also enables Tandy sound and composite video emulation.
  • ega – IBM Enhanced Graphics Adapter (EGA).
  • svga_paradise – Paradise PVGA1A SVGA card (no VESA VBE; 512K vmem by default, can be set to 256K or 1MB with vmemsize). This is the closest to IBM’s original VGA adapter.
  • svga_et3000 – Tseng Labs ET3000 SVGA card (no VESA VBE; fixed 512K vmem).
  • svga_et4000 – Tseng Labs ET4000 SVGA card (no VESA VBE; 1MB vmem by default, can be set to 256K or 512K with vmemsize).
  • svga_s3 default – S3 Trio64 (VESA VBE 2.0; 4MB vmem by default, can be set to 512K, 1MB, 2MB, or 8MB with vmemsize).
  • vesa_oldvbe – Same as svga_s3 but limited to VESA VBE 1.2.
  • vesa_nolfb – Same as svga_s3 (VESA VBE 2.0), plus the “no linear framebuffer” hack (needed only by a few games).
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 colour modes are excluded as they were not properly supported until the late ’90s. The 256-colour 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 colour 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 colour depth. Standard VGA modes (320Ă—200, 640Ă—480, etc.) are always available regardless of the vesa_modes setting.

Resolution 4-bit 8-bit 16-bit 24-bit 32-bit
640×400 — any — — 1 MB
640Ă—480 any any 1 MB 1 MB 2 MB
800×600 any any 1 MB — 2 MB
1024×768 any 1 MB 2 MB — 4 MB
1152×864 — 1 MB 2 MB 4 MB 4 MB
1280Ă—960 1 MB 2 MB 4 MB 4 MB 8 MB
1280Ă—1024 1 MB 2 MB 4 MB 4 MB 8 MB
1600Ă—1200 1 MB 2 MB 4 MB 8 MB 8 MB

The all mode adds the following on top of compatible:

  • 320Ă—200 and 320Ă—240 high colour modes (15/16/24/32-bit)
  • 320Ă—400 and 320Ă—480 modes in various depths
  • 400Ă—300 modes (8/15/16/24-bit)
  • 512Ă—384 modes (8/15/16/32-bit)
  • 848Ă—480 widescreen modes (8/15/16/32-bit)
dos_rate¶

Override the emulated DOS video mode’s refresh rate with a custom rate.

Possible values:

  • default default – Don’t override; use the emulated DOS video mode’s refresh rate.
  • host – Override the refresh rate of all DOS video modes with the refresh rate of your monitor. This might allow you to play some 70 Hz VGA games with perfect vsync on a 60 Hz fixed refresh rate monitor.
  • <number> – Override the refresh rate of all DOS video modes with a fixed rate specified in Hz (valid range is from 24.000 to 1000.000). This is a niche option for a select few fast-paced mid to late 1990s 3D games for high refresh rate gaming.

Important

Many games will misbehave when overriding the DOS video mode’s refresh rate with non-standard values. This can manifest in glitchy video, sped-up or slowed-down audio, jerky mouse movement, mouse button presses not being registered, and even gameplay bugs. Overriding the DOS refresh rate is a hack that only works acceptably with a small subset of all DOS games (typically mid to late 1990s games).

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.

Note

Only set this on a per-game basis when necessary as it slows down the whole emulator.

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:

  • maximum default – As fast as possible, no slowdown.
  • fast – Extra-high density (ED) floppy speed (~120 kB/s).
  • medium – High density (HD) floppy speed (~60 kB/s).
  • slow – Double density (DD) floppy speed (~30 kB/s).
hard_disk_speed¶

Set the emulated hard disk speed.

Possible values:

  • maximum default – As fast as possible, no slowdown.
  • fast – Typical mid-1990s hard disk speed (~15 MB/s).
  • medium – Typical early 1990s hard disk speed (~2.5 MB/s).
  • slow – Typical 1980s hard disk speed (~600 kB/s).

DOS & shell¶

language¶

Select the DOS messages language.

Possible values:

  • auto default – Detect the language from the host OS.
  • <value> – Load a translation from the given file.

Note

The following language files are available: de, en, es, fr, it, nl, pl, pt_BR, and ru. English is built-in; the rest is stored in the bundled resources/translations directory.

autoexec_section¶

How autoexec sections are handled from multiple config files.

Possible values:

  • join default – Combine them into one big section.
  • overwrite – Use the last one encountered, like other config settings.
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:

  • auto default – low if exec or dir is passed, otherwise high.
  • high – Show welcome banner and early stdout.
  • low – Show early stdout only.
  • quiet – Don’t show welcome banner or early stdout.
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:

  • repair default – Repair (and report) faults using adjacent blocks.
  • report – Report faults but otherwise proceed as-is.
  • allow – Allow faults to go unreported (hardware behaviour).
  • deny – Quit (and report) when faults are detected.