Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joncampbell123/dosbox-x/llms.txt

Use this file to discover all available pages before exploring further.

The [sdl] section controls how DOSBox-X presents itself to your operating system — covering everything from whether it starts in fullscreen, which graphics output backend is used, how the mouse is captured and released, clipboard integration, keyboard scan-code handling, and what text appears in the window title bar. Most settings here interact directly with the SDL (Simple DirectMedia Layer) library that DOSBox-X is built upon, so changes take effect only on the next launch unless noted otherwise.

​
Display Settings

​
fullscreen
boolean
default:"false"
Start DOSBox-X directly in fullscreen mode. Press F11+F (Windows) or F12+F (other platforms) to toggle back to windowed mode at any time.
​
fulldouble
boolean
default:"false"
Use double buffering in fullscreen mode. Can reduce screen flickering on some displays, but may slow down DOSBox-X on others. Only relevant when fullscreen=true.
​
fullresolution
string
default:"desktop"
Resolution to use when in fullscreen mode. Accepted values:
  • desktop — use the current native monitor resolution (recommended)
  • original — use the emulated DOS resolution
  • A fixed size such as 1024x768
Using your monitor’s native resolution together with aspect=true in [render] typically yields the sharpest image.
​
windowresolution
string
default:"original"
Scale the DOSBox-X window to this size when the output device supports hardware scaling. Note that output=surface does not support hardware scaling, so this setting has no effect in that mode. Use original to keep the native emulated resolution, or specify a size such as 1280x960.
​
windowposition
string
default:"-"
Position of the DOSBox-X window at startup, expressed as X,Y pixel coordinates (e.g. 1300,200). Use a bare , or leave empty to center the window, or - to open at the OS-default position.
​
display
integer
default:"0"
Screen or display number to use in a multi-monitor setup. 0 selects the system default primary display. Increment for additional monitors (1, 2, …).
​
output
string
default:"default"
Video output backend used to render the emulated screen. Available values:
  • default — let DOSBox-X choose the best available backend
  • surface — software rendering via SDL_Surface (no hardware scaling)
  • overlay — SDL overlay (legacy)
  • ttf — TrueType font output for text-mode programs
  • opengl — OpenGL with default filtering
  • openglnb — OpenGL nearest-neighbor (no bilinear filtering)
  • openglhq — OpenGL with high-quality filtering
  • openglpp — OpenGL pixel-perfect scaling
  • ddraw — DirectDraw (Windows only)
​
videodriver
string
default:""
Force a specific SDL video driver, overriding auto-detection. Examples: windib, windows, directx, x11, fbcon, dummy. Leave blank to let SDL choose automatically.
​
transparency
integer
default:"0"
Transparency level of the DOSBox-X window, applicable in both windowed and fullscreen modes on SDL2 builds and Windows SDL1 builds. Valid range is 0 (fully opaque) to 90 (highly transparent).
​
maximize
boolean
default:"false"
If set, the DOSBox-X window will be maximized at startup. Applies to SDL2 and Windows SDL1 builds only. For TTF output, use fullscreen=true instead.
​
overscan
integer
default:"0"
Width in pixels of the overscan border drawn around the image when using output=surface. Valid range is 0 (no border) to 10.

​
Mouse Settings

​
autolock
boolean
default:"false"
Automatically lock the mouse cursor inside the DOSBox-X window when you click on it. Press Ctrl+F10 to release (unlock) the mouse at any time.
​
autolock_feedback
string
default:"beep"
Visual or audible feedback given when the autolock state changes. Possible values:
  • none — no feedback
  • beep — system beep sound
  • flash — brief screen flash
​
middle_unlock
string
default:"manual"
Controls whether pressing the middle mouse button can unlock the mouse. Possible values:
  • none — middle button never unlocks
  • manual — works only when autolock=false
  • auto — works only when autolock=true
  • both — works regardless of the autolock setting
​
sensitivity
string
default:"100"
Mouse sensitivity percentage. A single number sets both axes (e.g. 100). Optionally provide a second value for the vertical axis (e.g. 100,-50 to invert vertical movement).
​
usesystemcursor
boolean
default:"false"
When enabled, DOSBox-X uses the host operating system mouse cursor rather than drawing a DOS-style cursor. This only takes effect while the mouse is unlocked/not captured.
​
mouse_emulation
string
default:"locked"
Determines when DOSBox-X emulates mouse movement rather than passing raw host mouse data directly. Possible values:
  • integration — emulate when the mouse is not locked
  • locked — emulate only when the mouse is locked (default)
  • always — always emulate mouse movement
  • never — never emulate; use raw host position at all times
High-DPI mice may feel slower but more precise when emulation is active.
​
mouse_wheel_key
integer
default:"-1"
Convert mouse wheel scroll events into keyboard key presses. Putting a negative sign in front disables the conversion for guest systems:
  • 0 — disabled
  • 1 — Up/Down arrow keys
  • 2 — Left/Right arrow keys
  • 3 — Page Up/Page Down keys
  • 4 — Ctrl+Up/Down arrows
  • 5 — Ctrl+Left/Right arrows
  • 6 — Ctrl+Page Up/Page Down
  • 7 — Ctrl+W/Z (WordStar-compatible)
  • -1 — disabled for guest systems (default)

​
Clipboard Settings

​
clip_mouse_button
string
default:"right"
Mouse button used for the shared clipboard copy/paste feature. Possible values:
  • right — right mouse button selects text and triggers copy/paste
  • middle — middle mouse button
  • arrows — use Home/End keys instead of a mouse button
  • none — disable clipboard mouse integration
​
clip_key_modifier
string
default:"shift"
Keyboard modifier that must be held while clicking the clipboard mouse button. Set to none for no modifier. Possible values include: none, ctrl, lctrl, rctrl, alt, lalt, ralt, shift, lshift, rshift, ctrlalt, ctrlshift, altshift, and their left/right variants.
​
clip_paste_bios
string
default:"default"
Controls whether clipboard text is pasted using BIOS keyboard functions or the keystroke injection method. Use default for automatic selection. Set to false when pasting into Windows 3.x/9x applications (e.g. Notepad) to use the keystroke method. Possible values: true, false, 1, 0, default.
​
clip_paste_speed
integer
default:"30"
Delay between injected keystrokes when pasting text from the clipboard. Increase the value if pasted text has missing characters; decrease it for applications that accept keystrokes quickly.

​
Keyboard Settings

​
usescancodes
string
default:"auto"
Prefer hardware scan codes over symbolic key names when reading keyboard input. This can improve compatibility with non-US keyboard layouts. With auto (the default), scan codes are enabled automatically for non-US keyboards in SDL1 builds. Possible values: true, false, 1, 0, auto.
​
mapperfile
string
default:"mapper-dosbox-x.map"
Path to the file used to load and save key/event mappings. The Reset Mapper function in the menus only works correctly when this is set to the default value.
​
waitonerror
boolean
default:"true"
If set, DOSBox-X will pause and wait for user input before closing the console window when an error occurs, allowing you to read the error message.
​
priority
string
default:"higher,normal"
Process priority levels for DOSBox-X, expressed as two comma-separated values. The first value is the priority when DOSBox-X is focused; the second is the priority when it is minimized or in the background. pause is valid only as the second value. Possible values: lowest, lower, normal, higher, highest, pause.

​
Title Bar Settings

​
titlebar
string
default:""
Custom text to append to the DOSBox-X window title bar. Leave blank to use only the default title.
​
showbasic
boolean
default:"true"
When set, the title bar displays basic information including the DOSBox-X version number and the current emulation speed.
​
showdetails
boolean
default:"false"
When set, the title bar additionally displays the cycles count (FPS) and the emulation speed as a percentage of real-time performance.
​
showmenu
boolean
default:"true"
Whether to display the menu bar at the top of the DOSBox-X window (on platforms and output modes that support it).

Build docs developers (and LLMs) love

Get started for freeTalk to us