Skip to content

Mouse¶

DOSBox Staging includes a built-in mouse driver which is enabled by default, so you don’t need to load a real DOS mouse driver manually (e.g., MOUSE.COM or CTMOUSE). The vast majority of DOS games that require a mouse will work out-of-the-box — you’ll only need to tinker with the mouse settings for a small handful of problematic games, or if you have very specific niche needs. The built-in driver provides lower latency and smoother movement than a real DOS mouse driver and uses less memory, so it’s the best option for most people.

To capture the mouse, click inside the DOSBox window. By default, the DOSBox Staging window’s titlebar indicates if the mouse is captured. To release the mouse, press the middle mouse button or Ctrl+F10 / Cmd+F10 (see Keyboard shortcuts). If your mouse has no middle button, the keyboard shortcut is your friend.

The mouse_raw_input setting bypasses your host OS’s mouse acceleration, giving you consistent sensitivity regardless of your desktop settings. This is particularly useful for games where precise mouse control matters (e.g., fast-paced FPS games).

Many DOS games differ wildly in how they handle mouse movement. In many games, horizontal and vertical mouse movement has different sensitivity. You can “normalise” the X and Y axis sensitivity or adjust the global sensitivity with the mouse_sensitivity setting.

DOS-era mice¶

The standard PC mouse throughout the DOS era had two buttons and no scroll wheel. Scroll wheels did not exist on consumer mice until Microsoft introduced the IntelliMouse in 1996, well into the twilight years of DOS gaming. The vast majority of DOS software was written for — and tested with — a simple two-button mouse.

DOSBox Staging emulates a two-button mouse by default (builtin_dos_mouse_driver_model = 2button), and this is the safest setting. Only a small number of games from the 90s support a third mouse button, and some games will misbehave if an unexpected middle button press is detected. If you know a game supports three buttons, enable it explicitly by setting the model to 3button. The wheel option exists for the rare DOS application or Windows 3.1 setup that can use a scroll wheel, but no DOS game is known to use it.

Serial mice¶

DOSBox Staging can emulate several serial (COM port) mouse types:

  • Microsoft mouse — 2 buttons, the most widely compatible type.
  • Logitech mouse — 3 buttons, mostly compatible with Microsoft mouse.
  • Wheel mouse — 3 buttons + wheel, mostly compatible with Microsoft mouse.
  • Mouse Systems mouse — 3 buttons, an older protocol NOT compatible with Microsoft mice. A few programs require this type.

To enable a serial mouse, use the SERIAL 1 mouse command (this attaches it to the COM1 port), or edit the Serial ports configuration. By default, DOSBox Staging tries to determine what type of mouse the program expects. See com_mouse_model for details.

Dual mouse gaming¶

Multiple physical mice can be mapped to specific emulated mouse interfaces, enabling two-player split-screen gaming using two USB mice on a single computer (e.g., in The Settlers and The Settlers II). Use the MOUSECTL command on the DOS command line to set the per-interface mouse configurations.

See the Dual mouse gaming wiki page for setup details.

Seamless mode¶

For Windows 3.1 running inside DOSBox, seamless mouse integration is available when using a compatible mouse driver — with this enabled, the mouse cursor can be moved freely between the host desktop and the DOSBox Staging window (see mouse_capture).

The built-in mouse driver has been reworked for better Windows 3.1 compatibility. The mouse now works properly in the Windows 3.1 MS-DOS Prompt run in a window — the previous garbled display and janky mouse movement issues are gone. If the new mouse code causes problems, set builtin_dos_mouse_driver to no-tsr to revert to previous behaviour.

Note

Multiple DOS windows under Windows 3.1 are not supported.

Troubleshooting¶

A few games have specific mouse issues that can be resolved with the built-in driver settings:

Configuration settings¶

You can set the mouse parameters in the [mouse] configuration section.

builtin_dos_mouse_driver¶

Built-in DOS mouse driver mode. It bypasses the PS/2 and serial (COM) ports and communicates with the mouse directly. This results in lower input lag, smoother movement, and increased mouse responsiveness, so only disable it and load a real DOS mouse driver if it’s really necessary (e.g., if a game is not compatible with the built-in driver).

Possible values:

  • on default – Simulate a mouse driver TSR program loaded from AUTOEXEC.BAT. This is the most compatible way to emulate the DOS mouse driver, but if it doesn’t work with your game, try the no-tsr setting.
  • no-tsr – Enable the mouse driver without simulating the TSR program. Let us know if it fixes any software not working with the on setting.
  • off – Disable the built-in mouse driver. You can still start it at runtime by executing the bundled MOUSE.COM from drive Z.

Note

  • The ps2_mouse_model and com_mouse_model settings have no effect on the built-in driver.

  • The driver is auto-disabled if you boot into real MS-DOS or Windows 9x under DOSBox. Under Windows 3.1, the driver is not disabled, but the Windows 3.1 mouse driver takes over.

  • To use a real DOS mouse driver (e.g., MOUSE.COM or CTMOUSE.EXE), configure the mouse type with ps2_mouse_model or com_mouse_model, then load the driver.

builtin_dos_mouse_driver_model¶

Set the mouse model to be simulated by the built-in DOS mouse driver.

Possible values:

  • 2button default – 2 buttons, the safest option for most games. The majority of DOS games only support 2 buttons, some might misbehave if the middle button is pressed.
  • 3button – 3 buttons, only supported by very few DOS games. Only use this if the game is known to support a 3-button mouse.
  • wheel – 3 buttons + wheel, supports the CuteMouse WheelAPI version 1.0. No DOS game uses the mouse wheel, only a handful of DOS applications and Windows 3.1 with special third-party drivers.
builtin_dos_mouse_driver_move_threshold¶

The smallest amount of mouse movement that will be reported to the guest (1 by default). Some DOS games cannot properly respond to small movements, which were hard to achieve using the imprecise ball mice of the era; in such case increase the amount to the smallest value that results in a proper cursor motion.

Possible values:

  • 1-9 – The smallest amount of movement to report, for both horizontal and vertical axes. 1 reports all the movements (default).
  • x,y – Separate values for horizontal and vertical axes, can be separated by spaces, commas, or semicolons.

Note

Known games requiring the threshold to be set to 2:

builtin_dos_mouse_driver_options¶

Additional built-in DOS mouse driver settings as a list of space or comma separated options (unset by default).

Possible values:

  • immediate – Update mouse movement counters immediately, without waiting for interrupt. May improve mouse latency in fast-paced games (arcade, FPS, etc.), but might cause issues in some titles.
  • modern – Emulate v7.0+ Microsoft mouse driver behaviour (instead of v6.0 and earlier). Only Descent II with the official Voodoo patch has been found to require this so far.
  • no-granularity – Disable mouse position granularity. Only enable if the game needs it. Only Joan of Arc: Siege & the Sword in Hercules mode has been found to require this so far.
com_mouse_model¶

Set the default COM (serial) mouse model, or in other words, the type of the virtual mouse plugged into the emulated COM ports. The setting has no effect on the built-in mouse driver (see builtin_dos_mouse_driver).

Possible values:

  • 2button – 2 buttons, Microsoft mouse.
  • 3button – 3 buttons, Logitech mouse; mostly compatible with Microsoft mouse.
  • wheel – 3 buttons + wheel; mostly compatible with Microsoft mouse.
  • msm – 3 buttons, Mouse Systems mouse; NOT compatible with Microsoft mouse.
  • 2button+msm – Automatic choice between 2button and msm.
  • 3button+msm – Automatic choice between 3button and msm.
  • wheel+msm default – Automatic choice between wheel and msm.

Note

Enable COM port mice in the [serial] section.

mouse_capture¶

Set the mouse capture behaviour.

Possible values:

  • onclick default – Capture the mouse when clicking any mouse button in the window.
  • onstart – Capture the mouse immediately on start. Might not work correctly on some host operating systems.
  • seamless – Let the mouse move seamlessly between the DOSBox window and the rest of the desktop; captures only with middle-click or hotkey. Seamless mouse does not work correctly with all the games. Windows 3.1 can be made compatible with a custom mouse driver.
  • nomouse – Hide the mouse and don’t send mouse input to the game.

Note

Use seamless mode for touch screens.

mouse_middle_release¶

Release the captured mouse by middle-clicking, and also capture it in seamless mode.

Possible values: on default, off

mouse_multi_display_aware¶

Allow seamless mouse behavior and mouse pointer release to work in fullscreen mode on systems with more than one display.

Possible values: on default, off

Note

You should disable this if it incorrectly detects multiple displays when only one should actually be used. This might happen if you are using mirrored display mode or using an AV receiver’s HDMI input for audio-only listening.

mouse_raw_input¶

Bypass the mouse acceleration and sensitivity settings of the host operating system. Works in fullscreen or when the mouse is captured in windowed mode.

Possible values: on default, off

mouse_sensitivity¶

Set global mouse sensitivity (100 by default).

Possible values:

  • <value> – Set sensitivity for both axes as a percentage (e.g., 150).
  • X,Y – Set X and Y axis sensitivity separately as percentages (e.g., 100,150). The two values can be separated by a space or a semicolon as well.

Note

  • Negative values invert an axis, zero disables it.

  • Sensitivity can be fine-tuned further per mouse interface with the internal MOUSECTL.COM command.

ps2_mouse_model¶

Set the PS/2 AUX port mouse model, or in other words, the type of the virtual mouse plugged into the emulated PS/2 mouse port. The setting has no effect on the built-in mouse driver (see builtin_dos_mouse_driver).

Possible values:

  • standard – 3 buttons, standard PS/2 mouse.
  • intellimouse – 3 buttons + wheel, Microsoft IntelliMouse.
  • explorer default – 5 buttons + wheel, Microsoft IntelliMouse Explorer.
  • none – No PS/2 mouse.
virtualbox_mouse¶

VirtualBox mouse interface. Fully compatible only with 3rd party Windows 3.1 driver.

Possible values: on default, off

Note

Requires PS/2 mouse to be enabled.

vmware_mouse¶

VMware mouse interface. Fully compatible only with 3rd party Windows 3.1 driver.

Possible values: on default, off

Note

Requires PS/2 mouse to be enabled.