1. Overview

Joystick Gremlin is a program that allows the configuration of joystick like devices, similar to what CH Control Manager and Thrustmaster's T.A.R.G.E.T. do for their respectively supported joysticks. However, Joystick Gremlin works with any device be it from different manufacturers or custom devices that appear as a joystick to Windows. Joystick Gremlin uses the virtual joysticks provided by vJoy to map physical to virtual inputs and apply various other transformations such as response curves to analogue axes. In addition to managing joysticks, Joystick Gremlin also provides keyboard macros, a flexible mode system, scripting using Python, and many other features.

The main features are:

  • Works with arbitrary joystick like devices
  • User interface for common configuration tasks
  • Merging of multiple physical devices into a single virtual device
  • Axis response curve and dead zone configuration
  • Arbitrary number of modes with inheritance and customizable mode switching
  • Macros with joystick, keybouard and mouse inputs
  • Python scripting support

Joystick Gremlin provides a graphical user interface, described in Section 3, which allows commonly performed tasks, such as input remapping, axis response curve setups, and macro recording to be performed easily. Functionality that is not accessible via the UI can be implemented through custom modules, explained in detail in Section 4.

1.1 Installation

Joystick Gremlin has one major dependency, vJoy which provides virtual joysticks which Joystick Gremlin feeds with data. Download links to the programs needed are listed below:

vJoy creates virtual joysticks which show up as a device in Windows and Joystick Gremlin uses these to forward inputs to them. The VC2010 package is required by Python but is likely already installed. The same goes for the VC2013 package which is required by vJoy but is most likely already installed on the machine. If one or both of these are missing they can be obtained from:

It's important that the VC Redistributables are the x86 ones, even if you're running a x64 system, as vJoy and Python require the 32bit libraries.

vJoy Configuration

In order to properly use Joystick Gremlin vJoy has to be configured first. This is done via the Configure vJoy program. This program allows setting the properties of all existing vJoy devices. Typically a single vJoy device is enough. In order to use 8-way POV hats with Joystick Gremlin the hats have the be configured as continuous in vJoy. The image below shows what a properly configured vJoy device looks like. Once everything is set as desired clicking Apply configures the vJoy device and the window can be closed.

VJoy configuration dialog with settings required for proper Joystick Gremlin operation.

1.2 Concepts

The following section introduces the terminology used by Joystick Gremlin. Next, the different concepts will be exapleined starting with individual actions and ending with a complete profile.

Input

An input is an axis, button, hat, or keyboard key on a physical device.

Action

An action is something Joystick Gremlin executes in response to the user activating a physical input. Examples include running a macro, sending button presses to vJoy, or changing to a different mode. Each action has a condition attached to it which can further dictate when an action is to be executed.

Container

A container holds one or more actions and uses them in the manner specific to the particular container. In the simplest case it simply executes the action(s). More complex cases are where the container decides which action(s) to execute based on the duration a button is held down.

Device

A device is a physical controller connected to the computer such as a joystick, pedal, or throttle. Each device has multiple inputs with their own associated actions.

Mode

A mode is a collection of actions associated with the inputs for each connected device. Each mode can inherit from one other mode, his parent. If a mode and its parent both define actions for the same input only the actions of the mode and not its parent are used. If the mode defines no actions for an input but the parent does the parent's actions are used. This allows having a common set of base actions that more specialised modes add to or change.

Profile

A profile is a folder which contains a XML configuration file together with any custom modules used. The profile contains the settings made via the user interface for each of the connected peripherals.

Example

The following is a simple example showing how the above introduced concepts work together. The profile contains two modes, Default and Landing and two physical devices Thrustmaster Warthog Stick and CH Pro Pedals. Both devices have varying actions executed on the exemplary inputs used which change between the two modes. The image on the right shows the conceptual nesting of the concepts as shown in the explicit example.

  • Profile: star_citizen.xml
    • Device:Thrustmaster Warthog Stick
      • Mode:Default
        • Input:Axis X
          • Container:Basic
            • Action:Map to vJoy Axis X
        • Input:Button 1
          • Container:Basic
            • Action:Map to vJoy Button 1
      • Mode:Landing
        • Input:Axis X
          • Container:Basic
            • Action:Map to vJoy Axis X
          • Container:Basic
            • Action:Apply response curve with deadzone
        • Input:Button 1
          • Container:Tempo
            • Action:Map to vJoy Button 10
            • Action:Map to vJoy Button 12
    • Device:CH Pro Throttle
      • Mode:Default
        • Input:Axis X
          • Container:Basic
            • Action:Map to vJoy Axis Z
          • Container:Basic
            • Action:Apply response curve
        • Input:Button 1
          • Action:Run chaff & flare macro
      • Mode:Landing
        • Input:Axis X
          • Container:Basic
            • Action:Map to vJoy Axis Z
          • Container:Basic
            • Action:Apply response curve
        • Input:Button 1
          • Container:Basic
            • Action:Map to vJoy Button 21
The image shows how the various concepts explained below relate to each other.