Skip to content

Key mapper¶

The key mapper lets you rebind any keyboard key, mouse button, or joystick control to any emulated input event. It is the central tool for customising controls in DOSBox Staging — whether you need to swap two keys, assign a gamepad button to a keyboard action, or build a complete controller profile for a keyboard-only game.

Open the key mapper by pressing Ctrl+F1 on Windows/Linux or Cmd+F1 on macOS during gameplay.

The key mapper interface¶

The key mapper displays a visual layout of a virtual keyboard and joystick. Each element on this layout represents an event — the input that DOSBox reports to the running DOS program. Clicking an event shows its current bindings: the physical keys, buttons, or axes that trigger it.

The interface provides the following controls:

  • Add — Bind a new physical key or button to the selected event. After clicking Add, press the key or button you want to assign.
  • Del — Remove the currently displayed binding from the selected event.
  • Next — Cycle through multiple bindings for the same event (an event can have more than one binding).
  • Exit — Return to the game. All changes are saved automatically.

The modifier checkboxes (mod1, mod2, mod3) let you create modified bindings — for example, requiring Ctrl to be held along with a key. This is how DOSBox’s own shortcuts work (e.g., Ctrl+F9 for shutdown).

Remapping keys¶

To swap two keys (for example, Y and Z on a German keyboard layout):

  1. Open the key mapper (Ctrl+F1 / Cmd+F1).
  2. Click the Y key on the virtual keyboard.
  3. Click Del to remove its default binding.
  4. Click Add, then press the physical Z key.
  5. Now click the Z key on the virtual keyboard.
  6. Click Del to remove its default binding.
  7. Click Add, then press the physical Y key.
  8. Click Exit to return to the game.

The same process works for any key — click the event on the virtual layout, remove the old binding, add a new one. All changes are saved automatically to the mapper file. To discard all customisations and start fresh, see Resetting the mapper.

Remapping joystick axes¶

To invert a joystick axis (e.g., reverse the Y-axis):

  1. Click the top of the Y-axis on the virtual joystick layout.
  2. Click Del to remove the default binding.
  3. Click Add, then push your physical joystick in the opposite direction.
  4. Repeat for the other direction of the same axis.
  5. Click Exit to return to the game.

Mapping controller buttons to keys¶

The key mapper can bind gamepad buttons to keyboard keys, which is how you play keyboard-only DOS games with a controller. The basic approach:

  1. Configure the game for keyboard-only controls (disable joystick in the game’s setup if possible).
  2. In the key mapper, click the key you want to trigger (e.g., the Up arrow on the virtual keyboard).
  3. Click Add, then press the corresponding button or direction on your controller.
  4. Repeat for all keys the game uses.
  5. Click Exit to return to the game.

Tip

When using a controller this way, set joysticktype = hidden in the [joystick] section so the game doesn’t detect the controller as a joystick. You may also want to set capture_mouse = nomouse in the [sdl] section to prevent analog stick movement from being interpreted as mouse input.

Mapper files¶

Mappings are saved to a mapper file — a text file that records every binding. By default, the file is named mapper-sdl2-<version>.map and is stored alongside your primary config file.

You can specify a custom mapper file path via the mapperfile setting in the [sdl] section:

[sdl]
mapperfile = my-game.map

DOSBox Staging ships with preconfigured mapper files for many games in the resources/mapperfiles directory. These can be loaded by name:

[sdl]
mapperfile = xbox/doom.map

Mapper file format¶

Each line in a mapper file maps an event name to one or more bindings:

event_name "binding_1" "binding_2"

For example:

key_esc "key 41" "stick_0 button 6"

This binds both the physical Escape key (key 41) and gamepad button 6 (Xbox Select) to the emulated Escape key.

Binding syntax¶

Keyboard bindings use the format key <scancode>, optionally followed by modifier flags (mod1, mod2, mod3):

key 41          (Escape)
key 66 mod1     (Ctrl+F9, i.e., mod1 = Ctrl)

Joystick bindings use the format stick_N <type> <id>, where:

  • stick_0 is the first controller
  • button <id> is a button press
  • axis <id> <direction> is an axis movement (0 = negative, 1 = positive)
  • hat <id> <direction> is a D-pad direction (1 = up, 2 = right, 4 = down, 8 = left)

Examples:

stick_0 button 0      (A button)
stick_0 axis 1 0      (left stick up)
stick_0 hat 0 1       (D-pad up)

Modifier bindings let you define a button as a modifier key, then use it in combination with other buttons:

mod_3 "stick_0 button 6"
hand_shutdown "key 66 mod1" "stick_0 button 7 mod3"

This defines gamepad button 6 (Select) as mod3, then binds Select+Start (button 7) to Ctrl+F9 (shutdown).

Xbox controller reference¶

For convenience, here are the common Xbox controller mappings:

Control Binding
A stick_0 button 0
B stick_0 button 1
X stick_0 button 2
Y stick_0 button 3
LB stick_0 button 4
RB stick_0 button 5
Select / Back stick_0 button 6
Start stick_0 button 7
L3 stick_0 button 9
R3 stick_0 button 10
D-pad up stick_0 hat 0 1
D-pad right stick_0 hat 0 2
D-pad down stick_0 hat 0 4
D-pad left stick_0 hat 0 8
Left stick X stick_0 axis 0 (0=left, 1=right)
Left stick Y stick_0 axis 1 (0=up, 1=down)
Right stick X stick_0 axis 3 (0=left, 1=right)
Right stick Y stick_0 axis 4 (0=up, 1=down)
LT stick_0 axis 2 2
RT stick_0 axis 5 2

Note

Button numbers may differ between controller brands. On Linux, you can use jstest to identify the correct IDs for your controller.

Resetting the mapper¶

If your key mappings get into a broken state, use the --erasemapper command line option to delete the default mapper file and reset all bindings to their defaults.

Warning

--erasemapper only deletes the default mapper file. If you’re using a custom mapperfile path, you’ll need to delete or edit that file manually.

Limitations¶

  • Only keyboard keys can be remapped to controller buttons and vice versa. Mouse buttons and mouse movement cannot be mapped through the key mapper.
  • The key mapper interface shows a US keyboard layout regardless of your physical keyboard layout. The bindings work correctly — only the visual representation in the mapper UI uses US layout positions.

For the full list of mappable events and their default bindings, see the Keymapper reference.