Gamepad/Joystick support

[fabi]

Joystick Control Support

Purpose

Most dedicated gaming devices don't rely on mouse or keyboard input for controlling their games,
but come with internal joypad sticks and extra buttons or external gamepads.
Some of them are able to play Wesnoth by installing Linux on them (Some "Playstation3" models for example).
The Wesnoth project offers binaries for the Linux based "OpenPandora" handheld.
On the other hand might also a PC gamer want to use his gamepad instead of the classic keyboard/mouse handling.

Wesnoth's newly added support for joystick devices aims for controlling the game entirely via the external or gaming device's controller.

Whenever this document talks about "Joystick", you can always assume that the other instances of the device family are meant as well.
This includes steering wheels (for racing games), joysticks, gamepads and some other exotic devices.
Although the development focuses on gamepads, support for other devices is a free side effect and not tested.

Concept

Currently Wesnoth is focused very much on mouse usage.
Without a mouse the game can't be controlled.

This can even be seen when reading the source code, many elements of the user interface are even grouped into the mouse handling classes.
I am not going to modularize the functionality but use the mouse handling classes for the joystick support as well.

The Cursor
In general, we don't need a mouse cursor to play a hexfield based strategy game.
Every action possible is bound to a hex field, having a cursor which is able to point on many different positions in a single hex is quite overkill.
When this document talks about Cursor it always refers to the golden hex border which marks the current highlighted hex field.
Thus joystick actions will only move the cursor from one hex field to another and nothing in between.

Over 80% of all actions in Wesnoth are Unit moves (maybe with attacking) that do not exceed the movement points of the units.
Thus we have two actions which dominate the playing process, Select Unit and Move Unit.
The other actions are things like recruit/recall, scouting the map and doing some stuff in the menus or dialogs.

Select Unit
Selecting a unit under your control can either be done by

• Moving the cursor over the unit's hex field and press the joystick button bound to Left Mouse Click.
• Binding the Next Unit and/or Previous Unit hotkey functions to a joystick button.

Status

The current development version from 1.9.8 on does have basic support for joystick devices.
Supported are up to 4 joysticks (numbers from 0-3) with up to 8 axes (numbers from 0-7).
Lacking support for controlling menus/dialogs, Wesnoth is still not playable without mouse usage.

A very rare equipment on joystick devices is an on-board trackball, I can't support it for now because I don't own or know a device featuring it.
Hints to suitable hardware or donations are always welcomed.

Targeted Devices

Gamepads are the most interesting type of joystick device when it comes to playing Wesnoth.
So I try to optimize the support for them at most and provide a pre configuration aimed at a Model Controller.
Most modern gamepads come with 2 analog sticks (2 x 2 axes), one or more hats and several buttons.
Some of them also feature 2 analog thrusters (one axis each).

Model Controller

I use the "Logitech Rumble Gamepad F510" to develop and test the code.
The pad comes with a switch (on the downside) between xInput (XBOX) and directInput (PC/WINDOWS).
It is connected via the USB and worked in both, Linux and Windows without any further actions when plugged in the default XBOX mode.
The signals are well distributed over the ranges for all axes, so I skipped any calibrating attempts, don't think it can get any better.
It is not recognized in Linux at all in PC/WINDOWS mode but works out of the box in XBOX mode.
I can confirm that it does work in GTA4 under Windows in XBOX mode as well, so I expect it to also do well in Wesnoth.
Hopefully every XBOX compatible controller works with the presets.

Features and Bindings

• 2-way Mode Switch
  • "X" xInput mode
  • "D" directInput mode
• 2 x 2-axes Analog Sticks
  • Left Side
    • X-Axis Axis0
    • Y-Axis Axis1
  • Right Side
    • X-Axis Axis3
    • Y-Axis Axis4
• 2 x 1-axis Analog Thrusters
  • Left Side "LT": Axis2
  • Right Side "RT": Axis5
• 4-way Hat on the left Side
  • Up
  • Down
  • Left
  • Right
• 11 x Bindable Button + 2 x Special Purpose Button
  • Pressing the sticks is a button each
    • Left Button9
    • Right Button10
  • Colored and labeled ones on the right
    • A Button0
      Bound to Okay
    • B Button1
      Bound to Cancel
    • X Button2
      Bound to
    • Y Button3
      Bound to
  • Center Buttons (from left to right)
    • "BACK" Button6 (with left arrow on it)
    • "Logitech" Button8 (with company logo on it)
    • "START" Button7 (with right arrow on it)
    • "MODE" button with LED used to switch between two modes of the left analog stick/steering cross:
      • LED off: Left stick controls axis0 and axis1 (Analog control). Steering cross controls the hat.(Default)
      • LED on: Steering cross controls axis0 and axis1 (Digital control). Left stick controls the hat.
    • "VIBRATION" Turns the rumble feature on/off
  • Backside Buttons
    • "LB" Button4 on the Left Back
    • "RB" Button5 on the Right Back.

OpenPandora

This Linux handheld comes with a digital (4 way?) Hat, 2 joystick-like analog controllers and 4 extra buttons.
The user can switch between mouse emulation / joystick mode by a terminal command.
In mouse emulation mode, Wesnoth can be played like used to on the PC.
Unlike the model controller it is not organized as a single controller with 6 axes but as 2 separate joysticks with 2 axes each.
Adjust your configuration to:

• Scroll_x: Joy0Axis0
• Scroll_y: Joy0Axis1
• Cursor_x: Joy1Axis0
• Cursor_y: Joy1Axis1
• Disable both Thruster Axis by setting their Joystick Number to "-1"

Get it Working

Some joysticks (only older ones?) need to get calibrated before usage. Look at your device driver's or operating system's tool in order to do so.

The joystick support is disabled by default.
Menu -> Preferences -> Advanced Preferences -> Joystick Support = Yes
enables it.
If your device and your taste fits to the default settings you are done.
Now define hotkey bindings for the controller's buttons.

Configuring and Fine-tuning

Joystick Axes
A joystick axis needs at least 3 arguments for operating:
Preferences->Advanced Preferences->Joystick: *

• The number (Range -1 ... 3) of the device it is located on. The value -1 disables the axis.
• The number (Range 0 ... 7) of the axis on the device.
• A "deadzone" value (Range 0 ... 16000) to ignore noise.

Use Cases
I have made up 3 usages for the two analog sticks, scrolling the screen, moving the "cursor" and a mouse simulation.
"Cursor" means the golden border which marks the hex field that is currently active.
Each of this use cases needs 2 axes bound to it best located on the same stick .
Thus you can choice between 2 of them with a "normal" gamepad.

• Scrolling the Screen
  Maximum scroll speed matches the speed of scrolling by the keyboard's direction keys.
  The scroll speed can be adjusted by the same old "Scroll Speed" preferences option that determines the keyboard scrolling speed.
• Cursor Movement
  Like all analog input all values below the deadzone are ignored.
  Values between deadzone and threshold lead to a single hex movement immediately.
  Values above the threshold lead to a linear accelerated movement of the cursor.
  • Threshold -- Defines the "One Hex per step" zone
  • Maximum Value -- Lower values gives faster movement
• Mouse Movement
  • speed

Analog Thrusters

• Increase scrolling/cursor speed
• Control the movement acceleration (not implemented yet)

Buttons and Hats
The buttons and hat positions are supported via the hotkey binding mechanism of Wesnoth.
You can assign them by simply pressing the button/hat of the gamepad/joystick in question instead of a key on your keyboard.
For using the device to control Wesnoth you should at least bind the newly added hotkey targets "Left Mouse Click" and "Right Mouse Click" to any of the controller's buttons.

Suggested Hotkey Bindings
Until a hotkey system that respects different contexts and/or multibinding is implemented it is not suitable to preconfigure most hotkeys since
it would deny the access to them for those users not owning a joystick.

So I offer this list of useful keybindings for now.
In order of importance:

1. Left Mouse Click
2. Right Mouse Click
3. Next Unit
4. Previous Unit
5. Show Enemy Moves
6. Show Best Enemy Moves
7. Stop Unit Movement
8. Redo
9. Undo
10. Recruit
11. Recall
12. End Turn
13. Unit Description

Known Issues:

• Footsteps are not set when the cursor is moved and one of your own unit is selected.
• The right mouse click emulation does not bring up the context menu. So it currently can only be used to deselect units.
• There is still no support for using the dialogs with the controller.
• On some laptop the accelerometer, which is used to park the hard-drive in case of an accident is implemented as a 3 axes joystick device.
  This means you can play Wesnoth by smashing the laptop against a wall. (not recommended)

[/list][/list]

Further Development

Hotkeys

Keyboard
Additional Hotkey bindings for moving the cursor and controlling menus/dialogs will make Wesnoth playable by keyboard only as well, a nice side effect.

Menus

Dialogs

[Iris]

More about locating the preferences file on our primary 3 supported platforms.

edit: manually editing the preferences file is no longer necessary.

[fabi]

Scrolling when the cursor reaches the map boarder changed to warp.

Added support for Hats,
updated the first post.

Does someone know a device with a (track)ball on it?

[Lord-Knightmare]

Scrolling when the cursor reaches the map boarder changed to warp.

Added support for Hats,
updated the first post.

Does someone know a device with a (track)ball on it?

I once had a mouse with a (track)ball on it. It was really difficult to use and one time the heavy ball fell on my foot (painful!)
Quick question: How can joysticks or gamepads be used in Wesnoth? Mouse and trackpads are better. Also touchscreens on the iPhone or iPad.

[fabi]

Once you get used to them trackballs are quite fine because they don't hurt the shoulder as much as the mouse.

I know that there are joysticks out there with balls because I see that the sdl library supports asking for their values,
and some laptops might also support reading their trackballs from the joystick driver.

Joysticks, especially analog ones might not be the best controller for Wesnoth, of course depending on your taste.
But they are spoken to through the same telephone number, so if I want to support gamepads I get the joystick support for free.

[ancestral]

Quick question: How can joysticks or gamepads be used in Wesnoth? Mouse and trackpads are better. Also touchscreens on the iPhone or iPad.

Good question. Probably not as well as a mouse or trackpad, but it may allow people to port BfW to other platforms more easily. The analog sticks can be used for cursor movement, and actually, you don’t need that much cursor control if you assign a button for ‘next unit’ and map other commonly used actions, like having a binding for right-click in order to access recruit and recall.

[fabi]

Quick question: How can joysticks or gamepads be used in Wesnoth? Mouse and trackpads are better. Also touchscreens on the iPhone or iPad.

Good question. Probably not as well as a mouse or trackpad, but it may allow people to port BfW to other platforms more easily. The analog sticks can be used for cursor movement, and actually, you don’t need that much cursor control if you assign a button for ‘next unit’ and map other commonly used actions, like having a binding for right-click in order to access recruit and recall.

I used to play "Battle Ilse", the first of the series on my Amiga with a digital joystick.
Battle Ilse is also a hex field based strategy game, the joystick interface worked quite well there.

"Battle Ilse II" was an IBM-PC/MS-DOS game.
It had mouse support but I was faster playing it with the keyboard, also hex field based strategy.

[fabi]

Added "Advanced Preferences" options.
Implemented a third "Mouse Pointer Control" use case.
Implemented a use case for one of the thrusters.
Enabled support for hotkey bound joystick buttons in the menus.
Joystick support is now disabled at default.

The first post has been updated accordingly.

[KDolecek]

Is Joystick still supported? I can't find option for enabling it in Advanced Preferences.

[fabi]

Is Joystick still supported? I can't find option for enabling it in Advanced Preferences.

Yes it is.
The feature was just not stable enough and it cluttered the advanced preferences too much.
You can still edit the preferences file with a text editor to enable it.

[hannayeah]

I have a Logitech Rumble Gamepad F510, which works without problems with other games. I am using Ubuntu 14.04 and BfW 1.11.15 (also tried 1.11.16). I modified the file data/advanced_preferences.cfg, and I can see the joystick options on the Menu Preferences->Advanced, (joystick support = yes). However, the gamepad does not seem to work at all. I cannot even assign any hotkeys or move any cursor. What can I do?

[fabi]

I have a Logitech Rumble Gamepad F510, which works without problems with other games. I am using Ubuntu 14.04 and BfW 1.11.15 (also tried 1.11.16). I modified the file data/advanced_preferences.cfg, and I can see the joystick options on the Menu Preferences->Advanced, (joystick support = yes). However, the gamepad does not seem to work at all. I cannot even assign any hotkeys or move any cursor. What can I do?

Hello, please give me a few days to check the joystick support,
I will come back to this thread then.

[galneon]

The topic post makes mention of the dinput/xinput switch on the F510, and says "Windows mode" (DirectInput) doesn't work at all in Linux. This suggests to me by omission that it is supposed to work in Windows? I don't see anything to specify dinput vs xinput in the advanced configuration file, and my dinput-only Logitech Cordless RumblePad 2 is not detected. I grew up on Master of Monsters and Langrisser and hope to recreate some of that magic with a gamepad. I'd especially like to use a Saturn pad, and while I could manage with Xpadder, I'd love to see improved native support.

With the emergence of HTPCs and dedicated multi-media-focused PCs making use of Steam Big Picture and other similar gamepad-loving front-ends, it seems proper gamepad support, including in-GUI configuration, is becoming a more pressing need by the day.

Edit: It's actually not working at all with an X360 controller either. So gamepads are not working in Linux or Windows (7 x64 in my case) at the moment, for either xinput or dinput. :/