Skip to content

Gamepad Controls

Jump to bottom
Zack Middleton edited this page Sep 17, 2017 · 8 revisions

In Spearmint, gamepads have mappings from joystick events to virtual bindable keys. If the device mapping is missing or the virtual keys are not bound to actions, the gamepad will not be usable in game.

Spearmint will automatically set the controller mapping if there is one built into SDL2 or in the gamecontrollerdb.txt file in the Spearmint binary downloads. Otherwise you need to manually configure the mapping in the console. In the future, there will probably be a way to do from the UI.

In any case, you will need to bind the gamepad to actions in the controls menu.

Joystick mappings are device specific so if you have multiple of the same controller for splitscreen you only need to configure the mapping once.

Manual joystick mappings are saved in the root of the home directory or in the settings directory in the Spearmint binary downloads. They are not cross-platform so the platform is in the filename. joy-(platform)-(device GUID).txt

Additional mappings

For additional pre-configured game controller mappings not built into SDL, save this as gamecontrollerdb.txt and put it in your Spearmint homepath (see below) or basepath (default: directory containing the engine executable).

Default homepath:

  • All: ./settings/ (portable homepath used in releases; settings is selected if it exists instead of system paths below)
  • Windows: %APPDATA%\Spearmint\
  • Linux: /home/username/.local/share/spearmint/
  • OSX: /Users/username/Library/Application Support/Spearmint/

Before Spearmint 0.5

  • Linux: /home/username/.spearmint/

Joystick Event Strings

Joystick event string format used by various commands and in saved mappings.

  • button0 / b0 refers to button 0.
  • hat0.2 / h0.2 refers to hat 0 with mask 1. UP is mask 1. RIGHT is mask 2. DOWN is mask 4. LEFT is mask 8.
  • +axis0 / +a0 refers to positive values of axis 0.
  • -axis0 / -a0 refers to negative values of axis 0.

0 to 15 are supported for button, hat, and axis.

The separation of positive and negative axis allows binding left(ex: -axis0)/right(ex: +axis0) and up(ex: -axis1)/down(ex: +axis1) of a joystick. Not to be confused to +moveup and -moveup for down and up key events.

Cvars

  • in_joystickDebug 1. This causes a message to be printed in the console showing joystick event each time you move an axis in a new direction or press a button.

Commands

  • joyremaplist. This shows the device name and event to key mappings.
  • joyremap <event> <key> Adds/replaces an event to key mapping. Where <event> is the button0 etc from in_joystickDebug messages and <key> is JOY_ (use tab to complete key names).
  • joyunmap <event> Remove an event to key mapping. where <event> is the 'button0' etc from in_joystickDebug messages.
  • joyunmapall Remove all event to key mappings.

Additional players use 2, 3, or 4 before the command name (e.g., 2joyremaplist, 2joyremap).

Multiple events can point to the same key. A single event cannot point to multiple keys.

How to manually configure

Using the console set in_joystickDebug 1. That way each time you move an axis or press a button it is shown in the console.

In the console use joyremap <event> <key> where <event> is the 'button0' etc from in_joystickDebug messages and <key> is JOY_*. You can type JOY_ and then press TAB to see a list of keys.

For player 2, 3, 4, use 2joyremap, 3joyremap, 4joyremap. However, joystick mappings are device specific so if you have multiple of the same controller you only need to configure it once.

After device mappings are set you'll need to using the controls menu and bind the gamepad to actions. To bind gamepad buttons/sticks/triggers you just have to press them, the same as keyboard and mouse buttons. It it doesn't work, check if you configure it correctly. Set in_joystickDebug 1 press the button/axis again and run joyremaplist command and look if it's on the list. If it's not on the list add it using joyremap.

It may seem weird to have to set up controls twice (mappings and binds). This will hopefully be dealt with later, by adding default joystick binds.

Virtual Keys

Full list of virtual joystick keys.

JOY_A // selects in UI
JOY_B // goes back in UI
JOY_X
JOY_Y
JOY_BACK
JOY_GUIDE
JOY_START

// D-Pad movement directions
JOY_DPAD_UP
JOY_DPAD_RIGHT
JOY_DPAD_DOWN
JOY_DPAD_LEFT

JOY_LEFTSHOULDER // upper left button
JOY_RIGHTSHOULDER

JOY_LEFTTRIGGER // lower left button
JOY_RIGHTTRIGGER

JOY_LEFTSTICK // press down on left stick
JOY_RIGHTSTICK

// joystick movement directions
JOY_LEFTSTICK_UP
JOY_LEFTSTICK_RIGHT
JOY_LEFTSTICK_DOWN
JOY_LEFTSTICK_LEFT

JOY_RIGHTSTICK_UP
JOY_RIGHTSTICK_RIGHT
JOY_RIGHTSTICK_DOWN
JOY_RIGHTSTICK_LEFT
Clone this wiki locally