ControllerBuddy

Visit the ControllerBuddy Homepage to get started.
Join the ControllerBuddy Discord for support and community discussions.

📖 Description

ControllerBuddy is an advanced gamepad mapping software that supports the creation of input profiles for complex target applications such as flight simulators.

In addition to the simple mapping of buttons and axes of a physical game controller to keyboard and mouse input, ControllerBuddy also supports feeding input commands to a virtual joystick device (vJoy / uinput).

The goal of ControllerBuddy is to allow the user to control target applications exclusively with a gamepad without ever having to reach for a keyboard or mouse.

⬇️ Download and Installation

📜 Install-Script

For the easiest way to install and update, use the ControllerBuddy-Install-Script.
It automates all the steps below and much more!

📦 Flatpak

Linux users may want to use the ControllerBuddy-Flatpak.

🧑‍🔧 Manual Installation

🪟 Windows x86-64

1. First download and install vJoy 2.2.2.0 on your system.
2. Click here and download the latest build of ControllerBuddy for Windows as a ZIP archive.
3. Extract the ControllerBuddy directory from the archive to any desired location on your hard-drive.
4. Run ControllerBuddy.exe inside the extracted ControllerBuddy directory.

🐧 Linux x86-64 / aarch64

1. Create a controllerbuddy group:

   sudo /usr/sbin/groupadd -f controllerbuddy

2. Add yourself to the group:

   sudo gpasswd -a "$USER" controllerbuddy

3. Allow the group to access uinput:

   echo 'KERNEL=="uinput", SUBSYSTEM=="misc", MODE="0660", GROUP="controllerbuddy"' | sudo tee /etc/udev/rules.d/99-controllerbuddy.rules

4. Load the uinput kernel module at boot:

   echo uinput | sudo tee -a /etc/modules-load.d/uinput.conf

5. Reboot
6. Click here and download the latest build of ControllerBuddy for Linux as a TGZ archive.
7. Extract the ControllerBuddy directory from the archive to any desired location on your hard-drive.
8. Run ControllerBuddy inside the extracted ControllerBuddy/bin directory.

✨ Features

• Map gamepad axes and buttons to highly customizable actions:
  • vJoy axis movements (absolute and relative)
  • vJoy button presses
  • Keyboard inputs
  • Mouse inputs
  • Cycles of actions
  • Mode switching
  • etc.
• Powerful user interface:
  • Allows the creation of mapping profiles
  • Configuration of settings
  • Support for light and dark UI themes
• In-game overlay:
  • Displays current mode
  • Can show current position of virtual axes
  • On-Screen-Keyboard that can be controlled by gamepad
  • Customizable position and colors
• Two modes of operation:
  • Local
  • Client-Server (experimental! use only in trusted networks!)
• Supported gamepads:
  • Xbox 360 Controller
  • Xbox One Controller
  • Xbox Series X|S Controller
  • Dual Shock 3
  • Dual Shock 4
  • Dual Sense
  • etc. (to check if your controller is supported please refer to the SDL_GameControllerDB project)
• Supported operating systems:
  • Windows / Linux (local / client / server)
  • macOS (server only - no binaries provided!)
• Language support for:
  • English
  • German

🗃️ Profiles

Profiles are used to configure your gamepad for a specific target application.

The general structure of a profile is as follows:

flowchart LR
 subgraph DefaultMode["Default Mode"]
    direction LR
        DefaultModeXButtonAction1["some Action"]
        DefaultModeXAxis("X Axis")
        DefaultModeXButtonAction2["another Action"]
        DefaultModeYButtonAction["some Action"]
        DefaultModeYAxis("Y Axis")
        DefaultModeAButtonAction1["some Action"]
        DefaultModeAButton("A Button")
        DefaultModeAButtonAction2["another Action"]
        DefaultModeYButton("Y Button")
        CycleAction["Cycle Action"]
        CycleActions["CycleActions"]
  end
 subgraph AnotherMode["Another Mode"]
    direction LR
        AnotherModeXAxis("X Axis")
        AnotherModeAButton("A Button")
        AnotherModeXAxisAction["some Action"]
        AnotherModeAButtonAction["some Action"]
  end
 subgraph YetAnotherMode["Yet Another Mode"]
    direction LR
        YetAnotherModeXAxis("X Axis")
        YetAnotherModeXAxisAction["some Action"]
  end
 subgraph CycleActions["Cycle"]
    direction LR
        CycleAction1["Action 1"]
        CycleAction2["Action 2"]
        CycleAction3["Action 3"]
  end
    Profile[("Profile (.json file)")] --- DefaultMode & AnotherMode & YetAnotherMode & BButton("B Button") & XButton("X Button")
    BButton --> AnotherModeAction["Mode Action"]
    XButton --> YetAnotherModeAction["Mode Action"]
    DefaultModeXAxis --> DefaultModeXButtonAction1 & DefaultModeXButtonAction2
    DefaultModeYAxis --> DefaultModeYButtonAction
    DefaultModeAButton --> DefaultModeAButtonAction1 & DefaultModeAButtonAction2
    DefaultModeYButton --> CycleAction
    CycleAction -. Perform Action Cycle .-> CycleActions
    CycleAction1 --> CycleAction2
    CycleAction2 --> CycleAction3
    CycleAction3 --> CycleAction1
    AnotherModeAction -. Switch to Mode .-> AnotherMode
    YetAnotherModeAction -. Switch to Mode .-> YetAnotherMode
    AnotherModeXAxis --> AnotherModeXAxisAction
    AnotherModeAButton --> AnotherModeAButtonAction
    YetAnotherModeXAxis --> YetAnotherModeXAxisAction

    style DefaultModeXAxis fill:#D5000055
    style DefaultModeYAxis fill:#2962FF55
    style DefaultModeAButton fill:#FFD60055
    style DefaultModeYButton fill:#00C85355
    style AnotherModeXAxis fill:#D5000055
    style AnotherModeAButton fill:#FFD60055
    style YetAnotherModeXAxis fill:#D5000055
    style BButton fill:#AA00FF55
    style XButton fill:#FF6D0055

Loading

When switching from one Mode to another, all the axes and buttons that are not used by the other mode retain their function from the previous mode. This works across multiple levels of modes.

Mode switching can be configured to work in two different ways:

• Default: works like the Shift key on your keyboard
• Toggle: works like the Caps Lock key

The ControllerBuddy-Profiles repository contains a number of well-thought-out profiles for many different flight simulators.

🏛️ Architecture

🏠 Local Mode

flowchart
 subgraph Local[Local]
        PhysicalController[Physical Controller]
        ControllerBuddy[ControllerBuddy]
        VJoy[vJoy + Win32 / uinput]
        TargetApplication[Target Application]
  end
    PhysicalController --> ControllerBuddy
    ControllerBuddy --> VJoy
    VJoy --> TargetApplication

Loading

🌐 Client-Server Mode

flowchart LR
 subgraph Server["Server"]
        PhysicalController[Physical Controller]
        ControllerBuddyServer[ControllerBuddy]
  end
 subgraph Client[Client]
        ControllerBuddyClient[ControllerBuddy]
        VJoy[vJoy + Win32 / uinput]
        TargetApplication[Target Application]
  end
    PhysicalController --> ControllerBuddyServer
    ControllerBuddyServer -. UDP .-> ControllerBuddyClient
    ControllerBuddyClient --> VJoy
    VJoy --> TargetApplication

Loading

🖼️ Screenshots

⌨️ Command Line Parameters

Parameter	Arguments	Description	Available for scripting
‑autostart	local / client / server	starts the specified mode of operation after launch	yes
‑export	file destination	exports a visualization of the current profile to the specified path	yes
‑gamecontrollerdb	file source	adds the SDL controller mappings from the specified file	yes
‑help		prints the help and exits	no
-host	hostname / IP address	sets the host address for outgoing network connections	yes
-password	password	sets the password for all network connections	yes
-port	port number	sets the server port for all network connections	yes
‑profile	file source	loads the specified profile after launch	yes
‑quit		quits the application	yes
‑save	file destination	save the current profile to the specified path	yes
‑skipMessageDialogs		skips all message dialogs	no
-timeout	timeout in milliseconds	sets the timeout in milliseconds for all network connections	yes
‑tray		launches the application to the system tray	yes
‑version		prints the version information and exits	no

If ControllerBuddy is already running, launching a second instance with any of the parameters marked as "available for scripting" will forward the specified action to the first instance and then exit immediately.

This mechanism allows seamless integration of ControllerBuddy into third-party applications.
For an example, see ControllerBuddy-DCS-Integration, which demonstrates how ControllerBuddy can be integrated into DCS World.

🙏 Attribution

ControllerBuddy makes use of these awesome software technologies and libraries:

• OpenJDK
• Apache Commons CLI
• ClassGraph
• dbus-java
• Error Prone
• FlatLaf
• Gson
• JSVG
• LWJGL - Lightweight Java Game Library 3
• SDL
• SDL_GameControllerDB
• SLF4J

🛠️ Building

If you want to build ControllerBuddy from source, this section might be helpful to get you started.
ControllerBuddy uses the Gradle build system, the following Gradle tasks are supported:

Task	Command
Generate version source file	gradlew generateVersion
Run SpotBugs and Spotless	gradlew check
Apply Spotless formatting	gradlew spotlessApply
Run ControllerBuddy	gradlew run
Install a jpackage image	gradlew installDist
Create a ZIP-compressed jpackage image	gradlew distZip
Create a TGZ-compressed jpackage image	gradlew distTar
Delete build and gen directories	gradlew clean

⚖️ License

GNU General Public License v3.0