2. Quick Start

2.1 Installation & Setup

On most sytems installing Joystick Gremlin only requires the installation of vJoy (Windows 10 1903 onwards) and Joystick Gremlin itself. Once vJoy is installed it is advisable to configure the vJoy device(s), using vJoyConf, to contain the desired number of axes, buttons, and hats.

VJoy configuration dialog with settings required for proper Joystick Gremlin operation.
When configuring the hat instances make sure to select continuous for their type.

2.2 Simple Profiles

The following is intended as a simple guide that introduces the concepts used in Joystick Gremlin by way of examples of how common tasks are achieved. One can think of Gremlin as a system that reacts to the user's input. This means that when the user does something Gremlin will react in a way specified by the user. In a sense the following summarizes the way Gremlin operates:

When I press this button on my joystick, I want the following to happen.

This is also reflected by the design of the UI which is divided into two halves. The left side lists all the physical inputs of a particular joystick, such as axes, buttons, and hats. The right side lists the actions associated with a particular physical input. Going back to the above idea the left hand side contains the “When I do” part while the right hand side reflects the “Gremlin does” part.

Joystick Gremlin UI

Basic Mappings

The simplest type of mappings are remapping a physical input to a virtual one with the Remap action. The other basic action is to map a physical input to a keyboard key or combination of keys using the Map to Keyboard action. Both of these actions will press and hold their virtual or simulated input for as long as the physical input is pressed.

These actions allow merging of multiple physical devices into a single one which can be useful for games that only recognize a single joystick. Mapping joystick buttons to keyboard keys allows using the default bindings of a game without having to rebind everything or if a game doesn't support joystick input.

Macros

Sometimes it's not enough to simply press and hold a button, for example when a sequence of keys needs to be pressed or an axis ramped up in a particular manner. This is where the Macro action comes into play. This action allows the recording and customizing of events that should be played back when the associated physical input is pressed.

Besides simply executing the macro once upon activation it is also possible to have a macro repeat in a variety of ways:

  • Repeat a fixed number of times
  • Repeat until the physical input is pressed again
  • Repeat as long as the physical input is pressed

Dealing with Axes

Axes often require additional configuration by adding deadzones to prevent accidental inputs or a response curves that modify the response to a physical input. This allows increasing or reducing the sensitivity of particular areas of physical input to tailor the axis to a user's preference. The horizontal axis of the curve editor reflects the physical deflection of the axis from minimum (left) to maximum (right) while the vertical axis reflects to output generated for the corresponding physical input.

2.3 Complex Profiles

While simple profiles as described above are already capable of supporting a large variety of setups, sometimes a bit more complexity is required to create a particular setup. This is where containers, conditions, and modes come into play.

Container

A container holds one or more actions and is capable of executing additional logic specific to the container. The simplest container type Basic simply executes all contained actions. This is the type which we've used implicitly when creating a simple profile. There are currently two more advanced containers, Tempo and Chain. The tempo container executes different sets of actions depending on how long the corresponding physical input is pressed. This allows using a single button for two different actions where, for example, one is used more often then the other. The chain container contains an arbitrary number of action sets and with each press of the associated physical input the next set of ations in the chain are executed. When the last action set was processed the first one will be run next. This can be used when a single physical button should be used to switch through different actions.

Condition

Sometimes it can be helpful to control the condition under which an action or container is executed. The execution can thus be conditioned on the state of other input devices such as joysticks or keyboard, as well as the state of the input associated with the action or container. This can be used to implement a shift state which normally executes one action but if a certain button is pressed a different action is executed.

Mode

In certain situations it can be beneficial to split a profile into several parts, called modes. Each mode can have their own individual set of physical input to action mappings. For example in flight simulators this can be used to have one mode for air combat, one for ground attack, and one for communications. One powerful feature of the mode system is the inheritance capability. A mode can inherit from a single parent which results in the child mode executing whatever action their parent defined for a given input if the child has no actions of their own specified. This allows creating basic modes and then fine tuning them in a child mode for particular usage scenarios without having to duplicate common functionalities.