Applications that use VControl have a uniform configuration file interface. It's reasonably customizable, but you'll be able to set up a desired configuration quickly and easily.
We'll work through the sample configuration file that ships with the demo utilities.
Each application has its own set of actions. Most of your configuration file will be indicating what keypresses or joystick actions (collectively, gestures) map to these actions.
We can map a gesture to an action by adding a line to our configuration file of the form
action-name: gesture-descriptor
Various gesture descriptors are available for indicating keystrokes, joystick axis motions, joystick button presses, and joystick hat motions.
It's also worth noting that everything in the configuration file is case-insensitive.
In the demo applications, the actions are Up,
Down, Left, Right,
Fire, and Special.
Anything from a hash symbol (#) to the end of the line
is ignored.
The first batch of configuration options sets up the keyboard
controls. The gesture descriptor for keystrokes is key
key-name, as seen below:
# Normal-key controls Up: key Up Down: key Down Left: key Left Right: key Right Fire: key Return Special: key Space # Number keypad controls Up: key Keypad-8 Down: key Keypad-2 Left: key Keypad-4 Right: key Keypad-6 Fire: key Keypad-Enter Special: key Keypad-0
Most keys are named by the symbol on the key (e.g. P.
The others have reasonably intuitive names, as seen in the
configuration file fragment above. A complete list is available on
the key names page.
It's also worth noticing that even just in the key configuration we are mapping multiple keys to the same value. This is an "OR" operation. If the user performs any of the gestures associated with "up", then "up" will be performed.
There are no cases in this configuration file of one gesture being mapped to multiple actions, but that works much as one would expect; the gesture becomes equivalent to taking both actions at once.
In order to use joystick controls, a joystick threshold must first be defined. This is an integer between 0 and 32766 that indicates how sensitive the joystick should be. The joystick library that VControl uses maps joystick axis locations to a value between -32767 and 32767; VControl will consider a gesture from the joystick to be valid if its absolute value exceeds the threshold. The precise value of this threshold will vary from joystick to joystick an according to player taste - a value of 10000-20000 is typical.
The threshold is set independently for each joystick. The line from our configuration file looks like this:
Joystick 0 threshold 15000
This done, we can now start assigning actions to joystick action motions. The gesture descriptors define a joystick port, a joystick axis, and then a polarity of negative or positive. Left, right, up, and down are pretty standard across joysticks, and these are assigned in the sample configuration file:
# Joystick axis controls Joystick 0 threshold 15000 Up: joystick 0 axis 1 negative Down: joystick 0 axis 1 positive Left: joystick 0 axis 0 negative Right: joystick 0 axis 0 positive
Fancier joysticks may have axes beyond these; experiment with your joystick settings to determine the proper settings for those.
Joystick buttons are pretty easy; each button has a number associated with it (check your joystick settings) and the gesture is identified by joystick port and button number as follows:
# Joystick button controls Fire: joystick 0 button 0 Special: joystick 0 button 1
Actions can be mapped to joystick hat motions as well. These usually only appear as point-of-view hats on top of the joystick, but some mixed digital-analog gamepads register their digital pad as a hat as well. Hats have numbers, like buttons, and actions are specified by joystick port, hat number, and hat direction:
# Joystick hat controls Up: joystick 0 hat 0 up Down: joystick 0 hat 0 down Left: joystick 0 hat 0 left Right: joystick 0 hat 0 right
Because VControl does not currently support key-chords (ANDing gestures together), you cannot currently map actions to diagonal motions of the hat.