Important Update!

Going forward, the Electronicks fork is the official home of JoyShockMapper. You can find the latest builds and updates there. Just as he has been a huge contributor to JSM while it was mine, I will continue to be involved now that it's his. You can read more about this decision on GyroWiki here.

JoyShockMapper

The Sony PlayStation DualSense, DualShock 4, Nintendo Switch JoyCons (used in pairs), and Nintendo Switch Pro Controller have much in common. They have many of the features expected of modern game controllers. They also have an incredibly versatile and underutilised input that their biggest rival (Microsoft's Xbox One controller) doesn't have: a 3-axis gyroscope (from here on, “gyro”).

My goal with JoyShockMapper is to enable you to play PC games with DS, DS4, JoyCons, and Pro Controllers even better than you can on their respective consoles -- and demonstrate that more games should use these features in these ways.

Download JoyShockMapper to use right away here!

For developers, version 2.2 and older serve as a reference implementation for using JoyShockLibrary to read inputs from DualShock 4, DualSense, JoyCons, and Pro Controller in your games. It now uses SDL2 for controller support, and JoyShockLibrary's developer has made code contributions to SDL2 to make sure it covers the same features.

JoyShockMapper is also a reference implementation for many of the best practices described on GyroWiki.

JoyShockMapper is primarily developed on Windows. JoyShockMapper should now be able to be built on and for Linux. See the instructions for that below. Please let us know if you have any trouble with this.

Contents

• Installation for Devs
  • Linux specific notes
• Installation for Players
• Quick Start
• Commands
  • Digital Inputs
    • Tap & Hold
    • Binding Modifiers
    • Simultaneous Press
    • Chorded Press
    • Double Press
    • Gyro Button
  • Analog Triggers
  • Stick Configuration
    • Standard AIM mode
    • FLICK mode and variants
    • Other mouse modes
    • Digital modes
    • Motion Stick and lean bindings
  • Gyro Mouse Inputs
  • Real World Calibration
    • Prerequisites
    • Calculating the real world calibration in a 3D game
    • Calculating the real world calibration in a 2D game
  • ViGEm Virtual Controller
    • Xbox bindings
    • DS4 bindings
  • Modeshifts
  • Miscellaneous Commands
• Configuration Files
  • OnStartup.txt
  • OnReset.txt
  • Autoload feature
• Known and Perceived Issues
• Troubleshooting
• Credits
• Helpful Resources
• License

Installation for Devs

JoyShockMapper was written in C++ and is built using CMake.

The project is structured into a set of platform-agnostic headers, while platform-specific source files can be found in their respective subdirectories. The following files are platform-agnostic:

1. include/JoyShockMapper.h - This header provides important type definitions that can be shared across the whole project. No variables are defined here, only constants.
2. include/InputHelpers.h - This is platform agnostic declaration of wrappers for OS function calls and features.
3. include/PlatformDefinitions.h - This is a set of declarations that create a common ground when dealing with platform-specific types and definitions.
4. include/TrayIcon.h - This is a self contained module used to display in Windows an icon in the system tray with a contextual menu.
5. include/Whitelister.h - This is another self contained Windows specific module that uses a socket to communicate with HIDCerberus and whitelist JSM, the Linux implementation, currently, is a stub.
6. include/CmdRegistry.h - This header defines the base command type and the CmdRegistry class that processes them.
7. include/JSMAssignment.hpp - Header for the templated class assignment commands
8. include/JSMVariable.hpp - Header for the templated core variable class and a few derivatives.
9. src/main.cpp - This does just about all the main logic of the application. The core processing logic should be kept in the other files as much as possible, and have the JSM specific logic in this file.
10. src/CmdRegistry.cpp - Implementation for the command line processing entry point.
11. src/operators.cpp - Implementation of all streaming and comparison operators for custom types declared in JoyShockMapper.h

The Windows implementation can be found in the following files:

1. src/win32/InputHelpers.cpp
2. src/win32/PlatformDefinitions.cpp
3. src/win32/Whitelister.cpp.cpp
4. include/win32/WindowsTrayIcon.h
5. src/win32/WindowsTrayIcon.cpp

The Linux implementation can be found in the following files:

1. src/linux/InputHelpers.cpp
2. src/linux/PlatformDefinitions.cpp
3. src/linux/Whitelister.cpp.cpp
4. include/linux/StatusNotifierItem.h
5. src/linux/StatusNotifierItem.cpp

Generate the project by runnning the following in a command prompt at the project root:

• Windows:
  • mkdir build && cd build
  • To create a Visual Studio x86 configuration: cmake .. -G "Visual Studio 16 2019" -A Win32 .
  • To create a Visual Studio x64 configuration: cmake .. -G "Visual Studio 16 2019" -A x64 .
• Linux:
  • mkdir build && cd build
  • cmake .. -DCMAKE_CXX_COMPILER=clang++ && cmake --build .

Linux specific notes

In order to build on Linux, the following dependencies must be met, with their respective development packages:

• gtk+3
• libappindicator3
• libevdev

Due to a bug in GCC, the project in its current form will only build with Clang.

JoyShockMapper was initially developed for Windows, this has the side-effect of some types used through the code-base are Windows specific. These have been redefined on Linux. This was done to keep changes to the core logic of the application to a minimum, and lower the chance of causing regressions for existing users.

The application requires rw access to /dev/uinput, and /dev/hidraw[0-n] (the actual device depends on the node allocated by the OS). This can be achieved by chown-ing the required device nodes to the user running the application, or by applying the udev rules found in dist/linux/50-joyshockmapper.rules, adding your user to the input group, and restarting the computer for the changes to take effect. More info on udev rules can be found at https://wiki.archlinux.org/index.php/Udev#About_udev_rules.

The application will work on both X11 and Wayland, though focused window detection only works on X11.

Installation for Players

The latest version of JoyShockMapper can always be found here. All you have to do is run JoyShockMapper.exe.

Included is a folder called GyroConfigs. This includes templates for creating new configurations for 2D and 3D games, and configuration files that include the settings used for simple Real World Calibration.

Quick Start

1. Connect your controller either with a usb cable or via bluetooth. Most modern controllers will be suported, including all Xbox, Playstation and Switch controllers.

2. Run the JoyShockMapper executable, and you should see a console window welcoming you to JoyShockMapper.

   • In the console you can start entering bindings : [button name] = [key name]. See Digital Inputs section for details on how buttons and keys are named.
   • Sticks, the gyro and Sony's analog triggers require some more configuration: typically some MODE you want to set, a sensitivity value and some other settings. Each is explained in the corresponding section. They follow the same format : [setting name] = [value]
   • Buttons and settings will display their current values if you only enter their name in the console.
   • Settings can display a short description of what they do if you enter [setting name] HELP
   • There are quite a few commands that do not work as assignments like above but just runs a function. For example RECONNECT_CONTROLLERS will update the controller listing, and RESET_MAPPINGS will set all settings and bindings to default. README will lead you to this document!
   • You will find a JoyShockMapper icon in the system tray: right click on it to display a quick list of commands and configuration files.

3. JoyShockMapper can load all the commands contained in a text