3. User Interface

In the following the various components of the user interface are introduced and their usage described. The UI should be sufficient for most common use cases. However, if functionality is missing, user created modules can provide these. Examples of how to achieve certain tasks using the tools provided by Joystick Gremlin are shown in 5. Examples.

Table of Contents

3.1 Overview

The following is a short overview of the different components that make up the main user interface, shown in the following image.

Joystick Gremlin UI

  1. Overview of all the inputs available for a given physical device. The small icons on the far right of each input indicate the type of actions associated with the input. The icons and their meaning are summarised in the table below.
  2. The right hand portion of the UI shows the list of containers and actions associated with the currently selected input. This panel allows configuring the actions to execute when the physical input is used.
  3. This drop down lists all available actions for this type of input. Pressing the "Add" button will embed the selected action in a basic container.
  4. This drop down contains the available containers for the currently selected input. Pressing the "Add" button inserts an empty container of the desired type.
  5. Each container can contain up to three tabs that handle various configurations. The Action tab allows the basic configuration of the actions. The Condition tab allows fine tuning under which conditions the action or container should be executed. Finally the Virtual Button allows configuring an axis or hat to be used like a button.
  6. The mode section allows changing the mode currently being configured.
  7. Each tab represents an individual device that is currently connected to the computer. The "Settings" tab allows configuring properties for the entire profile.
  8. Tool bar which holds the most commonly used actions, from left to right:
    • Open an existing profile.
    • Activate Joystick Gremlin, when active the button is pressed and a green icon is shown. This also changes the status bar display. Pressing the button while Joystick Gremlin is running will disabled it again.
  9. The status bar shows whether or not the program is currently running a profile. If the program is running the currently active mode is shown as well if code execution is paused. If the input repeater is active it's status is also shown in the far right.

The following table shows the different icons and the actions they represent.

Cycle modes Description
Macro Map to keyboard
Map to Mouse No-Op
Pause Play sound
Remap axis Remap button
Remap hat Response curve
Resume Split axis
Switch mode Switch to previous mode
Temporary mode switch Text-to-speech
Toggle pause & resume

3.2 Virtual Buttons

Each input has a natural behaviour or type of states it can be in. Certain actions, however, require a binary state reflecting that of buttons, i.e. pressed and released. In order for axis and hat inputs to support this they require to specify the condition under which they should be considered pressed and released, effectively turning them into a virtual button.

This is often needed, for example when using individual hat directions as buttons when a game doesn't support mapping individual hat directions. A common use with axis is to enable afterburners when the throttle reaches 100% thrust. This type of situations are where a virtual button is used. The details of these activation conditions is covered next.

Button and Keyboard Key

As these inputs are already binary there is no virtual button configuration needed.

Axis

Turning an axis into a virtual button by specifiying the range in which the virtual button is considered pressed.

Actions associated with axis inputs have a range based setup which simulates a button press when the axis enters the specified range and releases the virtual button when it leaves the range. In addition to being able to specify the range for the button you can also specify a direction in which said range has to be entered if desired. This allows triggering two different actions for the same range depending on the direction it is traversed.

Hat

Turning a hat into a button by selecting the directions which when pressed are considered to be pressing a virtual button.

The eight directions of POV hats can be treated as states in which the virtual button is considered pressed. It is possible to select multiple directions at once and any of the selected directions will be considered as part of a single virtual button.

3.3 Activation Conditions

Sometimes executing actions when a physical input is pressed is doesn't provide enough control over the execution of actions. To provide additional control over the execution of actions Gremlin allows the user to specify conditions under which action can or cannot be executed.

Typical usage scenarios for this would be the use of a modifier or shift key to change what a particular physical input does in certain situations. Another common case is to trigger different actions when a button is pressed or released, for example on throttles with switches rather then buttons.

Conditions can be placed on either each action individually or on the container as a whole.

As mentioned in 3.1. Overview the conditions are configured in the condition tab present in every container widget. The tab allows placing conditions on either every action individually or on the container as a whole. These conditions will dictate whether or not a particular action or container is executed when the corresponding physical input is used.

Activation conditions can check for the state of the action's physical input, a physical joystick input, or a keyboard input.

There are three types of conditions available:

Action
The Action condition checks whether or not the physical or virtual button triggering the action or container is pressed or released. This enables for example to run a macro when the physical button is released rather then when the button is pressed.
Joystick
The Joystick condition allows to use any physical joystick input as a condition. For buttons this is whether or not the button is pressed, for hats this is whether a particular direction is pressed, and for axis whether or not it currently is inside or outside a specified range.
Keyboard
The Keyboard conditions allows checking whether or not a particular keyboard key is pressed or not. This would typically be used to implement a modifier or shift key. To trigger different actions depending on the state of a key.
Multiple of these conditions can also be used jointly by specifying whether or not an action / container should be executed if any or all of the conditions are satisfied.

3.4 Containers

As the name implies containers are designed to hold one or more actions. In addition to grouping actions together a container can also apply further logic to groups of actions. Currently the following three types of containers exist.

Basic

Basic container widget.

This container simply holds a group of actions without any further specific functionality. This is the default container and suitable for most situations.

Chain

Chain container with two groups.

This container holds several independent groups of actions. Each time the physical action with which this container is associated the next action group is executed. When the last group in the chain is reached the first group is executed again. Additionally, a timeout can be set after which the chain is reset to the first entry.

Tempo

Tempo container with a remap action in both the short and long press action groups.

This container holds two groups of actions that get executed under different conditions. The first one is run when the input is pressed for a duration shorter then the specified delay. The second group is run when the input is pressed for longer then the specified delay. Whether the first group is executed with the input being pressed or only when it is released can be controlled by the activation setting.

3.5 Actions

As described in Section 1.2, each input, such as axis, button, hat, or keyboard key, can have multiple actions associated with it. However, not all inputs have access to the same types of actions as they are not applicable to them. In the following all available actions are described.

Each action has an activation condition associated with it, see Section 3.2, which can be used for fine grained control over them. Additionally, each input can also be configured to be always executed by checking the Always Execute box, see item 2 in the above image. Enabling this option results in actions associated with that input to be performed even if execution of callbacks is paused. This is mainly useful for resuming when execution has been paused.

Remapping

Axis remapping dialogue
Button remapping dialogue
Hat remapping dialogue

The remapping actions enable the user to propagate inputs from a physical joystick input to an equivalent vJoy input, i.e. axis to axis, button to button, and hat to hat. This allows the merging of multiple physical devices into a single device.

In the case of axis remapping the condition can be used to press a vJoy button while the axis in a certain range and release it once the range is left. This could for example be used to engage afterburners when a throttle is set to greater then 95%.

In most cases button remap actions should always trigger, i.e. on button press and release, as otherwise the forwarding to vJoy is incomplete.

Response Curve

Response curve action dialogue which allows the customisation of the joystick response as well as dead zones.

The response curve dialogue allows the customisation of the response produced by the joystick using the curve editor. The shape of the curve is controlled using a set of control points.

A new control point is added by a double left click in an empty area of the curve editor. Removing an existing control point is achieved by selecting the desired point and pressing the Del key on the keyboard. A single left click on a control point will mark the point as active. An active point can be dragged in the window to modify its position. Alternatively, the text fields below the curve editor allow for precise numerical control of the position.

Finally, the dead zones for the axis can be defined using the sliders and input fields at the bottom of the dialogue. The fields and sliders control the full deflection dead zone (1st and 4th field from the left) as well as the centre deflection dead zones (2nd and 3rd field).

Currently there are two types of response curve types available which are selected from the drop down menu at the top of the widget:

Cubic Spline
A simple spline with only control points dictating locations the curve has to pass through. No control over the shape is provided.
Cubic Bézier Spline
A more complex spline with control points and "handles" that can modify the shape of the overall curve. Importantly this allows to control how the curve approaches the end points of the curve.

A response curve mapping action always needs to be paired with a remap action, as otherwise the transformation will not have any effect.

In order for response curves to work properly the game has to be configured to use a linear 1:1 curve, as otherwise the two curve settings will interfere with each other producing undesirable results. This also applies when using vJoy response curves, if they are not linear the output produced by this action will be further modified.

Macro

Macro action dialogue allowing the recording of event sequences.

The macro dialogue allows the creation of macros capable of emitting keyoard, mouse, and joystick events with timing information between individual events.

Adding new keystrokes to a macro is done by pressing the Record button, after which all keystrokes will be recorded sequentially. To stop the recording simply press the Record button again. A pause can be added by pressing the Add Pause button, which will insert a pause after the currently selected entry. The length of the pause can be modified by double clicking the entry. Selecting an entry allows it to be moved up and down using the Up and Down buttons.

The stopwatch icon allows recording the input delays when recording a macro. The buttons with labels Axis, Button, Hat, Keyboard, and Mouse allow enabling or disabling those specific input events when recording a macro.

Clicking on any entry in the action list allows modifying that entry as appropriate for the input. Alternatively the entire action can also be changed through the dialog on the right hand side of the action. In the bottom right corner, the Macro Settings section allows changing the behaviour of the macro. Exclusive ensures that no other macro is running when this one is executing. The dropdown allows selecting a repeat mode for the macro.

None
The macro is executed exactly once.
Count
The macro is executed as often as specified with the specified delay between subsequent executions.
Hold
The macro is executed as long as the (virtual) button is held down with a configurable delay between subsequent executions of the macro.
Toggle
On the first press of the (virtual) button the macro is started and will repeatedly execute with the specified delay between executions until the (virtual) button is pressed again.

Each macro is executed independently, which means that multiple long running macros can have their key presses interfere with each other.

Map to Keyboard

Map to Keyboard dialogue which allows mapping of a physical key to an arbitrary keyboard key combination.

The map to keyboard action allows an arbitrary keyboard key sequence to be linked to a single physical input, such as a button. The specified keyboard sequence is pressed when the physical button is pressed and released when it is released.

Map to Mouse

Mapping an axis to a mouse direction, X or Y with speed range.
Mapping a hat to mouse directional control with speed range.

This action allows using joystick axes or a hat to control the relative motion of the mouse cursor. The speed values are in pixels per step while the acceleration on the hat regulates how long it takes to go from the slowest to the fastest movement speed.

Pause, Resume & Toggle

Pause dialogue which allows to temporarily stop the execution of callbacks.
Resume dialogue which allows Joystick Gremlin to execute callbacks again after enabling the pause state.
Toggle between pause and resume dialogue, which toggles between the two states.

The pause, resume, and toggle actions control whether or not Joystick Gremlin executes callbacks when inputs are used. When the application is paused only inputs that were configured to always execute will be executed.

In order for the resume and toggle actions to be useful they have to be defined as always execute, as otherwise it will be impossible to resume from the paused state.

Change Mode

Change mode action dialogue which allows to select the mode to switch to when the action is triggered.

This action will change the currently active mode of Joystick Gremlin to the one selected from the drop down list.

Temporary Mode Switch

Temporary mode switch dialogue which allows specifying a mode to switch to as long as the action is triggered, i.e. the "button" is held down.

This action will change the current mode to the one specified when the button or button-like input is pressed. When the input is released the mode will automatically be changed back to the previous one.

Switch to Previous Mode

Dialogue of the action that switches to the previously active mode.

This action changes the current mode to the previously active one.

Cycle Modes

The dialogue of the cycle modes action allows adding various action which will be cycled through in order on each subsequent activation.

This action allows the configuration of a list of modes that are cycled through consecutively with each activation. In case that the currently active mode is not part of the list the first mode in the list will be activated.

New modes can be added by selecting the desired mode in the drop down list and pressing the Add button. The currently selected mode can be deleted by pressing the Delete button and moved up or down with the Up and Down button respectively.

Split Axis

Split axis dialog which allows splitting a single axis into two virtual ones.

This action allows splitting a single physical axis into two virtual ones. The value at which the physical axis is split can be adjusted by the user.

Play Sound

Plays the sound file specified at the given volume when the action is triggered.

This action allows the specification of a sound to be played with the desired volume when the action is triggered. Only one sound can be played at a time and new sounds will interrupt currently running ones.

Text to Speech

Text to speech action dialogue which allows entering text to be spoken by Joystick Gremlin.

This action allows arbitrary text to be spoken by Joystick Gremlin. The system knows how to replace some values with current information. The currently known replacements are listed below.

Expression Replacement
${current_mode} The name of the currently active mode

The text segments are spoken in the order they are requested and as such queueing multiple long segments can lead to significant delays between them being triggered and played.

No Operation

An action that performs no function other then to serve as a place holder.

Sometimes one wants an empty or no operation action that can be used as a place holder. For example to use a tempo container with no short press action. This action allows having an action inside a container without it doing anything.

3.6 Profile Settings

The Settings tab allows configuring settings that apply to the entire profile. This includes:

  • Defining how the initial mode is selected
  • Defining which vJoy devices are to be treated as physical inputs rather then outputs
  • Configuring the initial value of vJoy output axis on activation

Profile settings tab showing three vJoy devices and their configuration

Startup Mode

By default Gremlin uses a heuristic to figure out which mode to select upon activation of a profile. The mode selected is either the one that was active upon deactivation of Gremlin or the first mode without a parent in alphabetical order.

If this heuristic is not suitable the drop down allows the selection of any of the modes present in the profile to be selected as the initial mode.

vJoy as Input

In certain scenarios it can be desirable to have Gremlin treat a vJoy device as an input, e.g. when another program feeds a vJoy device but doesn't offer some features that Gremlin does. By checking the box next to the vJoy devices it will be treated as an input rather then output device.

When a vJoy device is declared as an input device Gremlin will no longer show it as a target in the Remap action and other similar actions. However, a tab for that vJoy device will appear which allows adding actions to all the axes, buttons, and hats of the vJoy device remapping to other vJoy (output) devices.

This features was newly introduced in Release 11 and as such may still contain bugs and unforeseen interactions with other parts of Gremlin.

Initial vJoy Axes Values

By default Gremlin sets all vJoy axes to a value of 0.0, i.e. centered. In some situations this is not ideal, for example a throttle, and as such this section allows setting the initial value to use for each axis.

3.7 Tools

In the following section the various tools provided by Joystick Gremlin are described. They can be accessed via the Tools and Actions menus.

Mode Manager

The mode manager allows the creation, deletion, and renaming of modes as well as defining their relationships.

The mode manager, accessed via Tools > Manage Modes, allows users to create new modes, delete existing ones and define which mode inherits configurations from others. Pressing "Add Mode" adds a new mode, pressing the button to the right of each mode with the x on it deletes it, and the button with a pen icon allows renaming a mode. Finally, using the drop down menu each mode can be configured to inherit from one other mode by selecting its name or not inheriting from any mode by selecting the "None" entry.

A mode that inhertits from another is typicalled called a child and will perform the same actions as its parent when no actions are defined for a particular input.

User Module Manager

The user module manager dialogue lists the custom modules Joystick Gremlin should load.

While the UI allows to perform common tasks there will be functionality that is not present. However, by using custom modules, described in Section 3, the limitations of the UI can easily be overcome. The module configuration dialogue is accessed via Tools > Manage Custom Modules. The modules listed there will be loaded in conjunction with the UI based configuration, allowing the use of the UI for common tasks and implementing specialised functionality in a custom module. Modules are added via the Add button which prompts the selection of the file on the system. Likewise removing modules is done by selecting the desired module and pressing the Delete button.

Merge Axis

This dialog allows the specification of two physical axis that should be combined into a single virtual one.

This dialog allows the selection of any arbitrary two physical axis and the virtual axis their combined output should be assigned to.

Input Repeater

When enabling the Input Repeater option, while Joystick Gremlin is active, via Tools > Input Repeater, Joystick Gremlin will repeat the last remapped input after a short wait period. This allows button presses and axes movements to be mapped in-game when the game detects the physical device's inputs instead of the virtual ones. The status bar provides information about the current action of the input repeater when activated.

Device Information

The device information dialogue provides an overview of the inputs and identification of the various joystick devices present in the system.

Information about connected devices can be accessed via Tools > Device Information. This window provides an overview of the devices known to Joystick Gremlin, listing the name as well as some basic information about each device. The System ID represents the order in which the devices are seen by the operating system, while the Hardware ID is an identifier that is unique to each device.

The currently used hardware id is not device, but product specific. As such it can not distinguish between two identical joysticks. To distinguish those the system id is used. When there are no duplicate devices present the system id is ignored.

Calibration

The calibration tool allows the calibration of all connected devices independent of Windows.

The axes calibration screen, accessed via Tools > Calibration, allows the calibration of connected devices independent of Windows. The window shows the current, minimum, centre, and maximum value for each analogue axis of the selected device. To calibrate the axes simply move them through their full range of motions and press the Centred button when all axes are centred. Once done press Save to save the calibration of the currently selected device to the configuration file.

Input Viewer

The input viewer allows visualizing the values of axes, buttons, and hats of all devices recognized by Gremlin.

The input viewer allows visualizing the input from the physical as well as virtual devices. The window shows recognized devices and data visualizations for their inputs on the left hand side while the visualizations themselves will be shown in the right hand side of the window.

Cheatsheet Generation

To help remember complex setups Joystick Gremlin has the ability to create PDF and HTML cheatsheets of the current profile. The output lists for each mode the actions of the available devices together with the user provided description.

Create 1:1 Mapping

In order to make the initial setup quicker Joystick Gremlin can create a 1:1 mapping for the user. To do this select the entry from the Actions menu. This will result in each input being assigned the next free corresponding action, i.e. buttons are mapped to buttons and axes to axes.

Profile Creator

In order to enable easier sharing of configurations, even if different devices are used, the Profile Creator allows creating a new profile from an existing one. When started the tool asks for a profile to use as a template and then presents all the bound actions within to the user for binding to their particular devices.

The interface shows:
  • Description of the action
  • Type of actions used
  • What input the action is currently bound to
Clicking on the button allows the user to press / move the input they wish to associate with the particular action. Once this is done the button will reflect this binding. When all desired actions are bound the configuration can be saved as a new profile by clicking on the save button.

This tool is only capable of binding actions defined via the UI and if custom modules are used in a profile those will not be automatically adapted to the new devices used.

Log viewer

The log viewer allows the user to easily check the content of the log file as well as clear it.

The log viewer can be accessed via Tools > Options and allows easy viewing of both the system and user log files. The display is updated whenever the content of the log changes. Clearing the entire log is alos possible from this screen.

Swap Devices

When multiple identical devices are present Gremlin relies on the ID assigned to them by Windows in addition to the hardware ID to identify devices. This can sometimes fail when Windows reassigns its IDs. To work around this issue the Swap Devices dialog allows swapping the configuration from one device to another identical one.

This dialog allows swapping the actions assigned to identical devices between each other.

3.8 Options



The options dialogue which is used to set some default settings and configure the profiles associated with programs.

There are several user controllable options in Joystick Gremlin which can be controlled via the options dialogue, accessible through Tools > Options.

General

The following options are accessible via the General tab:

Highlight currently used input
This option causes Joystick Gremlin to automatically select the input configuration matching the physical input's being used.
Closing minimizes to system tray
Instead of quiting the application when it is closed, Joystick Gremlin is simply minimized to the system tray.
Start Joystick Gremlin minimized
Launches Joystick Gremlin minimized to the system tray instead of opening the main window.
Show message when changing mode
Displays a windows notification when the mode is changed.
Default action
Sets the action to be pre-selected in action selection drop down menus

Profiles

The Profiles tab exposes the following options:

Automatically load profile based on current application
This option makes Joystick Gremlin to automatically load and activate the profile assigned to the currently active application.

The drop down menu and input fields allow selecting the executable and the profile associated with it. When an executable specified in this list is active the profile associated with it is automatically loaded and activated. Once the profile stops being the active one Joystick Gremlin is automatically stopped.

The edit icon allows changing the path of the selected executable or to enter a regular expression that will be used to match against the foreground process. Joystick Gremln will first attempt to find a direct match for an existing file and once this fails attempt to use the remaining entries as regular expressions, picking the first successful match.

HidGuardian

HidGuardian is a tool that solves the problem of a game seeing both the physical device and the virtual device at the same time and processing these inputs in unwanted ways. HidGuardian is capable of hiding those physical devices from all non whitelisted programs, thus effectively allowing games to be fooled into believing only the virtual devices exist.

If Gremlin is started with admin priviliedges and HidGuardian (ideally installed through this tool) is present this tab allows hiding and unhiding devices. Once a device's status was changed it has to be unplugged and replugged for HidGuardian to be able to use it.

This feature as well as HidGuardian are still in development. In fact HidGuardian is undergoing rework and as such newer versions will not work with Gremlin and this feature will be updated once HidGuardian has stabilized.

3.9 Command Line Options

Joystick Gremlin allows controlling the following options via command line parameters:
  • Loading a specific profile
  • Enabling the program on launch

Profile Loading

By passing the --profile parameter followed by the path to the profile to load Joystick Gremlin will load the specified profile.

Enabling on Launch

Passing the --enable flag will enable Joystick Gremlin once the program has been fully loaded.

Start Minimized

Passing the --start-minimized option to Joystick Gremlin will cause it to launch minimized.