Joysticks

Joysticks and Gamepads

Table of contents (click to expand)

• Introduction
• General notes
• Calibration
• DOSBox Staging Config Settings
  • joysticktype
  • timed
  • autofire
  • swap34
  • buttonwrap
  • deadzone
  • use_joy_calibration_hotkeys
  • joy_x_calibration
  • joy_y_calibration
• Using modern controllers
  • PS3 DualShock3 controller
  • PS4 DualShock4 controller
  • Xbox 360 controller
  • XBox One controller

Introduction

While game consoles and most home-computers back in the day had two or more Joystick ports, the IBM PC and its early clones typically had none. IBM did provide a DA-15 game-port adapter option, but few people had it, or a matching PC compatible Joystick. As such most PC games are designed to be played with the keyboard, or for later games with the mouse.

Eventually the IBM game port, just like the PC, was cloned and found its way onto multi-IO cards and soundcards of the era. But even if PCs had a game port, few owned a matching joystick. And even nowadays games on modern PCs are often played with a keyboard and mouse.

This is also reflected in most DOS games. Joystick support is not universal, and even if the game supports a joystick, the game often has to be specifically configured for it.

The game port's DA-15 connector was designed to support two joysticks, via a seperate Y-splitter cable. With each joystick having two-axis and two-trigger buttons. But there are some joysticks with more axis and/or buttons that require the whole port by themselves, and therefore only a single joystick could be attached, this is referred below as "4axis".

DOSBox Staging uses SDL for input, which includes joysticks and gamepads. Any SDL supported joystick or gamepad will automatically become available within DOSBox Staging as a joystick. Assuming the joystick or gamepad is properly attached and recognized by the host OS before DOSBox Staging is started.

For games that do not support Joysticks themselves, DOSBox Staging provides the possibility to map joystick or gamepad inputs to keyboard presses using the mapper.

General notes

You may have to experiment with different settings to find the optimal settings for different games, and will probably end up with game-specific DOSBox Staging configurations.

If a game supports joystick input, but you cannot get it working properly (e.g., joystick not detected by the game), you may have to play with the cycles= setting. Many games are sensitive to CPU speed issues when it comes to their joystick support.

Please note that DOS software supporting joystick input may not react properly when you adjust CPU cycles while they are being run, i.e. either find the appropriate number of CPU cycles it requires first or restart it for a consistent joystick experience.

DOSBox Staging also supports 6 buttons joysticks, to enable support, set the emulated joystick type to 4axis. You will find that 5th and 6th buttons are in fact the negative sides of the 2nd port joystick axes. To remedy this problem and use buttons instead, in the mapper add bindings to 'Axis 3 X-' and 'Axis 4 Y-' to buttons you which to act as 5th and 6th buttons on your device. Note that you can only have a single 6 buttons joystick at any time, this is due to how they are implemented (such a device in fact uses both joystick ports).

Calibration

While most home computers and game consoles back in the day used digital joysticks or controllers, the IBM PC instead used analogue joysticks.

This has both advantages and disadvantages. An advantage is that it allows for more accurate axis controls, a disadvantage is that it requires calibration.

NOTE: An exception to this are some late PC gaming joysticks, like the MS SideWinder which encoded digital signals over the analogue connection. This however required special software support. These type of joysticks are not emulated by DOSBox Staging.

PC joysticks often had physical calibration sliders, or some games would give you the ability to perform software calibration. Others will silently perform a centre calibration on startup, or may omit it completely.

DOSBox Staging has some built-in capability to calibrate joysticks using keyboard hotkeys. See the use_joy_calibration_hotkeys config option, documented below.

Vogons user jfnagel posted a few joystick test programs for DOS that you may want to try in DOSBox Staging to see how your controller behaves with various settings and how accurate the calibration is.

Emulated CPU speed can also cause havoc on a games joystick calibration routine. You may need to adjust the cycles= setting if you encounter issues.

DOSBox Staging config settings

Joystick options can be set in the [joystick] section of the DOSBox Staging config file.

joysticktype

• Default value: auto
• Possible values: auto, 2axis, 4axis, 4axis_2, fcs, ch, hidden, disabled

NOTE: If changing this setting, or if you saved the mapperfile without joystick connected or with a different joystick, remember to reset dosbox's mapperfile. Otherwise, the new setting will not work properly (or at all).

Value	Description
auto	Chooses joystick emulation option depending on real gamepads or joysticks attached when starting DOSBox Staging. - If only a single joystick or gamepad is detected on startup, the option will default to 4axis. - If two joysticks or gamepads are detected on startup, the option will default to 2axis. TIP: If you're having problems with the game when using a joystick, try setting it explicitly to 2axis mode.
2axis	With this option, you can have two joysticks, but each joystick will only have two axis and two trigger buttons. Most PC games with joystick support are compatible with this mode. With a modern gamepad, the two axis will be mapped to the left analogue stick. And the trigger buttons to two of the gamepads face buttons.
4axis	With this option, you can only have a single joystick, but the joystick will have four axis and four trigger buttons. Alternatively, depending on the gamepad, you can also have two axis, and six trigger buttons. Few PC games really support more than 2 axis and 2 trigger buttons. But this mode is, generally, compatible with those games. With a modern gamepad, the axis will be mapped to both the left and right analogue sticks. And the trigger buttons to the four gamepad face buttons.
4axis_2	Same as the 4axis option, but as the second PC joystick.
fcs	Emulate an original Thrustmaster FCS (Flight Control Stick). Typically used for flight simulators. Only select this option, if the game specifically supports this joystick. Only supports one controller, with 3-axes, 4 buttons and 1 hat.
ch	Emulate an original CH Flightstick. Typically used for flight simulators. Only select this option, if the game specifically supports this joystick. Only supports one controller, with 4-axes, 6 buttons and 1 hat. But you cannot press more than one button at the same time.
hidden	Hide any attached joysticks from DOS programs, but enable them for use by the mapper.
disabled	Disables joystick emulation.

timed

• Default value: true
• Possible values: true, false

Enable timed intervals for axis. Experiment with this option, if your joystick drifts (away) or does not calibrate properly inside DOSBox Staging, while it works fine outside DOSBox Staging.

autofire

• Default value: false
• Possible values: true, false

Continuously fires as long as you keep the trigger button pressed.

swap34

• Default value: false
• Possible values: true, false

Swap the 3rd and the 4th axis. can be useful for certain joysticks.

buttonwrap

• Default value: false
• Possible values: true, false

Enable button wrapping at the number of emulated buttons.

deadzone

• Default value: 10
• Possible values: 0-100

The deadzone option allows an axis to be at rest when it is below a certain threshold. As a result, axis value at rest will stay fairly stable whereas previously a lot of jitter could be seen. A default value of 10 should do fine on contemporary joysticks or gamepads. A higher value might be needed for older devices as they tend to loosen over time.

A value of 100 will turn the stick into a d-pad.

This option will apply to all axis for all attached joysticks or gamepads.

use_joy_calibration_hotkeys

• Default value: false
• Possible values: true, false

Enable hotkeys to allow realtime calibration of the joystick's X and Y axes. Only consider this if in-game calibration fails and other settings have been tried.

• Ctrl/Cmd+Arrow-keys adjust the axis' scalar value:
  • Left and Right diminish or magnify the x-axis scalar, respectively.
    • Down and Up diminish or magnify the y-axis scalar, respectively.
• Alt+Arrow-keys adjust the axis' offset position:
  • Left and Right shift X-axis offset in the given direction.
    • Down and Up shift the Y-axis offset in the given direction.
• Reset the X and Y calibration using Ctrl+Delete and Ctrl+Home, respectively.

Each tap will report X or Y calibration values you can set below. When you find parameters that work, quit the game, switch this setting back to disabled, and populate the reported calibration parameters.

Example:

The output from the DOSBox Staging log will look something like this after pressing the joystick calibration hotkeys:

JOYSTICK: x_calibration = 0.61299,0.02
JOYSTICK: y_calibration = 0.52725,0.02

Once you found suitable settings, take those values and add them to your DOSBox Staging config file.

joy_x_calibration

• Default value: auto
• Possible values: auto or number,number

Apply X-axis calibration parameters from the joystick calibration hotkeys.

joy_y_calibration

• Default value: auto
• Possible values: auto or number,number

Apply Y-axis calibration parameters from the joystick calibration hotkeys.

Using modern controllers

An few examples for using more modern game controllers.

PS3 DualShock3 controller

These controllers can support two modes of operation:

• Direct USB attached
  • It will appear as an input device.
• Regular Bluetooth attached
  • It will work as a wireless controller. But setting this up can be tricky.

NOTE: If the controller does not work, be sure you pressed the PS button and only one of the player indicator LEDs on the controller is lid.

NOTE: The way the PS3 DS3 controller connects wireless, is different from typical Bluetooth devices. It is necessary to first connect the controller via USB, where the device driver must then write the computers Bluetooth MAC address into the controller. The controller will afterwards try to connect to the computers MAC address when turned on in wireless mode. The first time the controller tries to connect to the PC, you should get a notification, asking you to allow the device to connect. This works fairly well (although slow) with authentic Sony PS3 controllers, but 3rd party controllers may fail to connect, or may almost immediately again disconnect.

On Linux when plugged in with USB, the controller will immediately work. Bluetooth as mentioned can be more tricky, but at least authentic Sony PS3 controllers should work.

On Windows you will need to install a 3rd party utility and driver. See here for instructions: https://www.digitaltrends.com/gaming/how-to-connect-a-ps3-controller-to-a-pc

PS4 DualShock4 controller

These controllers can support three modes of operation:

• Direct USB attached
  • It will appear as both an input device, and as an audio device.
• Regular Bluetooth attached
  • It will work as a wireless controller. The headphone jack will not work.
• Sony DUALSHOCK 4 USB Wireless Adapter
  • With this optional (and rather expensive) adapter, it will appear to the operating system as being USB attached with support for both input and audio.

NOTE: Since the DualShock4 has an integrated 3.5mm headphone jack, audio may get redirected to this headphone jack when plugged in.

On Linux the PS4 controller is handled by the hid_sony kernel module, and will immediately work when plugged in over USB, no special configuration is required. This includes the headphone jack, and the touchpad which will control the mouse.

Likewise, connecting it over Bluetooth is as simple as putting the controller into pairing mode (hold the 'share' button and then the PS button, until it starts to blink rapidly), and discover it in your Bluetooth settings where it will show up as a "Wireless Controller".

In 2axis mode, the left analogue stick and the X (Button 1) and O (Button 2) buttons will be used.

On Windows it is necessary to manually install drivers. See https://github.com/Ryochan7/DS4Windows for the download and instructions.

NOTE: If the controller does not work, be sure you pressed the PS button and only one of the player indicator LEDs on the controller is lid.

Xbox 360 controller

The Xbox 360 Wireless controller does not work when plugged in over USB, and cannot be connected over Bluetooth.

This is a limitation of the Xbox 360 Wireless controller. Its special USB cable can only be used for charging and identification. All controller inputs are transmitted wireless using a proprietary RF protocol. As such, when used with a PC requires the Xbox 360 Wireless Gaming Receiver USB dongle, which was sold separately.

Due to its proprietary wireless protocol, it will also not work with other Bluetooth wireless dongles like the 8BitDo Wireless USB Adapter.

The Xbox 360 Wired controller is not effected, and works when plugged in over USB.

On Linux the Wired controller, and the Wireless controller (with Wireless Gaming Receiver dongle) typically works out of the box. In some cases, like on Fedora it is necessary to manually install the xpad kernel module (part of the kernel-modules-extra package).

On Windows the controllers will automatically work with Windows 8 and later. See the following links for more details:

• https://support.xbox.com/help/xbox-360/xbox-on-windows/accessories/xbox-controller-for-windows-setup

Xbox One controller

Both the XBox One Wired and Wireless controllers work when connected over USB.

For wireless, it depends on the hardware revision of the controller. Original controller models use a proprietary RF protocol and require the Xbox One Wireless Adapter USB dongle for use with a PC.

Later hardware revisions (with a 3.5mm headphone jack on the bottom of the controller), can optionally connect over Bluetooth.

NOTE: The USB Wireless dongles for the Xbox 360 and Xbox One controllers are not interchangeable.