Editor · Messages · Gamepad
A control can have multiple gamepad messages configured. Gamepad messages can only be received and not sent.
A gamepad message is configured to wait for a certain game controller input on one or multiple configured gamepad connections, and apply the received input value to one of the control's values or properties.
For portability between platforms, and to allow TouchOSC documents to be shared with users using different input devices, all game controllers are mapped to a standard Xbox 360-like controller layout.
This is the same strategy as employed by the ubiquitous Steam game client and the popular SDL2 game development library, and we support the same mapping database format as these.
On desktop platforms, if no mapping can be found for the game controller in the included database, TouchOSC will output a warning to the log view upon connection.
It is possible to update and customize TouchOSC's internal database of controller mappings by placing a text file following SDL2's game controller database format in TouchOSC's configuration directory, found at the following location for each platform:
- Windows:
%AppData%/TouchOSC/ - macOS:
~/Library/Application Support/net.hexler.lex/ - Linux:
~/.TouchOSC/
TouchOSC will look for a file called gamecontrollerdb.txt at this path once at application launch, and if
found, will try to load and apply that configuration.
Enabled
The enabled state of the message.
If a message is not enabled, it will not be processed when a matching input is received.
Connections
The connections that the message should be received on. The numbers refer to the numbered configured game controllers in the Gamepad connections configuration.
The special connection labelled '∞' enables receiving messages on all connections.
Input
The type of input received from the game controller.
The input can be one of the following:
- STICK_LEFT_X
The x-axis of the left analog stick
- STICK_LEFT_Y
the y-axis of the left analog stick
- STICK_RIGHT_X
The x-axis of the right analog stick
- STICK_RIGHT_Y
The y-axis of the right analog stick
- TRIGGER_LEFT
The left trigger at the back of the controller
- TRIGGER_RIGHT
The right trigger at the back of the controller
- BUTTON_UP
The up button on the directional pad
- BUTTON_DOWN
The down button on the directional pad
- BUTTON_LEFT
The left button on the directional pad
- BUTTON_RIGHT
The right button on the directional pad
- BUTTON_A
The face button often labelled A
- BUTTON_B
The face button often labelled B
- BUTTON_X
The face button often labelled X
- BUTTON_Y
The face button often labelled Y
- BUTTON_STICK_LEFT
The button input pressing down on the left analog stick
- BUTTON_STICK_RIGHT
The button input pressing down on the right analog stick
- BUMPER_LEFT
The left bumper button at the back of the controller
- BUMPER_RIGHT
The right bumper button at the back of the controller
- BUTTON_START
The center button often labelled 'Start'
- BUTTON_SELECT
The center button often labelled 'Select' or 'Back'
- BUTTON_HOME
The button at the center of the controller, often showing a logo of the controller manufacturer or game console
Target
The target value or property of the message.
When the configured input is detected on any of the enabled connections, the received numeric value of the input will be written to the target value or property selected here, after scaling and conversion has been applied.
The target can be one of the following types:
- VALUE
One of the target control's value objects.
- PROPERTY
One of the target control's properties.
Scaling
The scaling to apply to the input value.
The input value will be scaled in the same way as other received message values according to the following formula, which is the inverse of the scaling that is applied to outgoing messages of all message types:
value = (input - min) / (max - min)
It's easiest to think of this inverse scaling this way: Setting min and max to the expected
minimum and maximum input values received from the game controller, this transformation will produce a
value ranging from 0 to 1.
Conversion
The type conversion to apply to the input value.
The conversion can be one of the following types:
- BOOLEAN
- INTEGER
- FLOAT
- STRING