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:
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.
The enabled state of the message.
If a message is not enabled, it will not be processed when a matching input is received.
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.
The type of input received from the game controller.
The input can be one of the following:
The x-axis of the left analog stick
the y-axis of the left analog stick
The x-axis of the right analog stick
The y-axis of the right analog stick
The left trigger at the back of the controller
The right trigger at the back of the controller
The up button on the directional pad
The down button on the directional pad
The left button on the directional pad
The right button on the directional pad
The face button often labelled A
The face button often labelled B
The face button often labelled X
The face button often labelled Y
The button input pressing down on the left analog stick
The button input pressing down on the right analog stick
The left bumper button at the back of the controller
The right bumper button at the back of the controller
The center button often labelled 'Start'
The center button often labelled 'Select' or 'Back'
The button at the center of the controller, often showing a logo of the controller manufacturer or game console
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:
Any of the target control's value objects.
Any of the target control's properties.
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
max to the expected
minimum and maximum input values received from the game controller, this transformation will produce a
value ranging from
The type conversion to apply to the input value.
The conversion can be one of the following types: