TJoy - Touch Joystick Virtual Controller Project

<p align="center"><img src="https://user-images.githubusercontent.com/1366615/178935496-19a2dac5-84fe-4d93-ab24-385bed2f243a.png" /></p>

TJoy Touch Portal Plugin

This project is currently implemented as a "plugin" for the Touch Portal macro launcher software, designed for integrating with virtual gaming controllers. It currently fully supports the vJoy virtual joystick driver, ScpVBus (a.k.a vXBox) virtual XBox 360 gamepad driver, and ViGEm Bus driver for XBox 360 and DualShock 4 controller emulation.

Features

• Supports all controls provided by joystick driver(s):
  • vJoy: Up to 16 joystick devices, each with up to 8 axes, 4 continuous (360 degree) or 4-way POV hats, and 128 buttons.
  • ScpVBus: Up to 4 "XBox 360" type gamepads each with 4 joystick axes, 2 slider (trigger) axes, one 8-way D-Pad, and 11 other buttons.
  • ViGEm Bus: Up to 4 each of "XBox 360" and "PS DualShock 4" type gamepads with all associated controls.
  • (That's up to 192 axes, 76 Hats/D-Pads, and 2,192 possible buttons, in case you were wondering :)
• Use Touch Portal Actions and Sliders for all joystick controls (joystick buttons are actions only).
• Multiple options for each joystick control. Click, hold, or toggle buttons/hats, adjust axis range and precision, reverse axis direction, set up custom mixes, button sequences, and much more.
• Control multiple joystick buttons/axes/hats simultaneously (usually up to 10, depending on your touchscreen and device performance).
• Use calculations in action data fields, for example to control a joystick axis value based on the value of a variable or state, with basic math operators available (+, -, *, /, % (modulo)).
• Use multiple linked controls for the same axis, for example a "coarse" slider over the full range of an axis and a "fine" slider which controls a smaller range of the same axis. Linked controls are updated in real-time.
• Optional reporting of current joystick axis positions and button states at a configurable update frequency.
• Connect and disconnect to joystick devices on demand (automatically or via an action) and monitor current connection status via events.

Examples

Check what's in the assets folder in this repo. There are a few demo/test pages with screenshots and a small icon pack. These are not included with the release download, so download them separately from that folder if you want.

Setup

Supported Virtual Joystick/Gamepad Drivers

• vJoy v2.1.x series driver for virtual joysticks. Latest signed and working version is here: v2.1.9.1.
  • Reports are that it works on Windows 11, but it may need a few tries to install. I have personally only tested on Windows 10 21H2.
  • In theory TJoy should work with older 2.x versions but I haven't tested.
  • vJoy v2.2.x series drivers are currently only partially supported. Specifically the joystick states are not available. It does not currently support Win11 either. This is pending more testing and may change if it eventually gets fixed for Win11. I recommend using v2.1.9 for now.
• ScpVbus v1.7.1.2 ("vXBox") for emulating up to 4 XBox 360-style Gamepads: Download at https://github.com/shauleiz/ScpVBus/releases.
• ViGEm Bus v1.21.442 for emulating up to 4 XBox 360 and/or PS DualShock4 style Gamepads: Download at https://github.com/ViGEm/ViGEmBus/releases.

Requirements:

• One or more virtual joystick/gamepad driver from the list of supported ones above. You must install driver(s) separately otherwise TJoy can do nothing useful.
• Touch Portal Pro (paid version) for Windows, v3.0.6 or newer.
• The latest version of this plugin: get the TJoy-TouchPortal-Plugin-X.X.X.X.tpp file from the latest release on the Releases page.

Install:

1. Install (or already have installed) one or more of the supported virtual joystick drivers listed above. Also of course you will need Touch Portal installed.
2. The TJoy plugin is distributed and installed as a standard Touch Portal .tpp plugin file. If you know how to import a plugin, just do that and skip to the next Configure section.
3. Import the plugin:
   1. Start/open Touch Portal.
   2. Click the Settings "gear" icon at the top-right and select "Import plugin..." from the menu.
   3. Browse to where you downloaded this plugin's .tpp file and select it.
   4. When prompted by Touch Portal to trust the plugin startup script, select "Trust Always" or "Yes" (the source code is public!).
      • "Trust Always" will automatically start the plugin each time Touch Portal starts.
      • "Yes" will start the plugin this time and then prompt again each time Touch Portal starts.
      • If you select "No" then you can still start the plugin manually from Touch Portal's Settings -> Plug-ins dialog.
4. That's it. You should now have the plugin's actions available to you in Touch Portal.

Configure

Several settings are available in the Touch Portal Settings window (select Plug-ins on the left, then TJoy Touch Portal Plugin from the drop-down menu). The options are as follows:

• Default Device: The name/number of the default device configured on your system which you would like to use. All the action and slider controls are set to use the "Default" device by default. If you mostly use one device, this prevents the need to select a device for each action/slider. The default device will also be connected automatically at startup.

  • You can enter just a number here, for example for vJoy you would specify a device ID of 1-16, or for one of the gamepad drivers it could be 1-4. If you have multiple drivers installed, it will look for a vJoy joystick first, then an ScpVBus XBox360 device, and finally a ViGEm XBox360.
  • You can also be more specific here by providing a device (driver) name as well as a number. For example: vJoy 1 or vXBox 4. The device names are as follows (case insensitive): vJoy (vJoy driver), vXBox (ScpVBus driver), vgeXBox and vgeDS4 (ViGEm driver).
  • Enter zero to disable the default device feature. In this case you will need to select a specific device to use for every action/slider you configure.

• Auto-Connect Device On Action/Slider Event: When enabled (1), activating an action (button) or moving a slider which controls a non-connected device will automatically try connecting to it. Set to 0 to disable.

• Position State Report Update Interval: The plugin can optionally send the current joystick axis and button values as TP States. Enter how often to send these updates, in milliseconds, or enter zero to disable them.

• Report Raw Axis Values: When reporting is enabled (above), the axis values are by default sent as percentages. Enable this option to get the actual raw values instead (eg. for vJoy axis it's 0-32767).

• Buttons To Report: vJoy can have up to 128 buttons configured. That's a lot of states to send over if you don't need them all. Here you can specify the maximum number of buttons to report (eg. 8 to get buttons 1-8), or a range of buttons to report for, for example 32 - 64 to get only those buttons states sent over. Enter zero to not send any button states at all.

Known Issues

• Please note that support for detecting when a slider has been released (is no longer being touched) is spotty at the moment. This is very useful in a joystick-like control, but due to some vague language on the Touch Portal API reference site, it turned out this feature maybe wasn't even meant to exist in TP. It does, however, work most of the time if you pause for a fraction of a second before releasing the slider.
  • I have a request in with the TP authors to improve this detection so it is more reliable, since it is vital for things like "self-centering" joystick axes. Please help by also requesting this feature on the Touch Portal Discord server or via other support means.

Update Notificat