Visit the ControllerBuddy Homepage to get started.
Join the ControllerBuddy Discord for support and community discussions.
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.
For the easiest way to install and update, use the ControllerBuddy-Install-Script.
It automates all the steps below and much more!
Linux users may want to use the ControllerBuddy-Flatpak.
- First download and install vJoy 2.2.2.0 on your system.
- Click here and download the latest build of ControllerBuddy for Windows as a ZIP archive.
- Extract the
ControllerBuddydirectory from the archive to any desired location on your hard-drive. - Run
ControllerBuddy.exeinside the extractedControllerBuddydirectory.
- Create a controllerbuddy group:
sudo /usr/sbin/groupadd -f controllerbuddy
- Add yourself to the group:
sudo gpasswd -a "$USER" controllerbuddy - Allow the group to access uinput:
echo 'KERNEL=="uinput", SUBSYSTEM=="misc", MODE="0660", GROUP="controllerbuddy"' | sudo tee /etc/udev/rules.d/99-controllerbuddy.rules
- Load the uinput kernel module at boot:
echo uinput | sudo tee -a /etc/modules-load.d/uinput.conf
- Reboot
- Click here and download the latest build of ControllerBuddy for Linux as a TGZ archive.
- Extract the
ControllerBuddydirectory from the archive to any desired location on your hard-drive. - Run
ControllerBuddyinside the extractedControllerBuddy/bindirectory.
- 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 are used to configure your gamepad for a specific target application.
The general structure of a profile is as follows:
flowchart LR
Profile[("Profile (.json file)")] ---- DefaultMode
Profile --- BButton(B Button) & XButton(X Button)
BButton --> BButtonModeAction[/Mode Action/] -. switch to .-> Mode1
XButton --> XButtonModeAction[/Mode Action/] -. switch to .-> Mode2
subgraph DefaultMode[Default Mode]
direction LR
DefaultModeXAxis(X Axis) --> DefaultModeXAxisAction1[/Action 1/] & DefaultModeXAxisAction2[/Action 2/]
DefaultModeYAxis(Y Axis) --> DefaultModeYAxisAction[/Action/]
DefaultModeAButton(A Button) --> DefaultModeAButtonAction1[/Action 1/] & DefaultModeAButtonAction2[/Action 2/]
DefaultModeYButton(Y Button) --> CycleAction[/Cycle Action/] -. perform next .-> CycleActions
DefaultModeXAxis ~~~ CycleAction
DefaultModeYAxis ~~~ CycleAction
DefaultModeAButton ~~~ CycleAction
DefaultModeYButton ~~~ CycleAction
subgraph CycleActions[Cycle]
CycleAction1[/Action 1/] --> CycleAction2[/Action 2/] --> CycleAction3[/Action 3/] --> CycleAction1
end
end
subgraph Mode1[Mode 1]
direction LR
Mode1XAxis(X Axis) --> Mode1XAxisAction[/Action/]
Mode1AButton(A Button) --> Mode1AButtonAction[/Action/]
end
subgraph Mode2[Mode 2]
direction LR
Mode2XAxis(X Axis) --> Mode2XAxisAction1[/Action 1/] & Mode2XAxisAction2[/Action 2/]
end
style DefaultModeXAxis fill:#D5000055
style Mode1XAxis fill:#D5000055
style Mode2XAxis fill:#D5000055
style DefaultModeAButton fill:#FFD60055
style Mode1AButton fill:#FFD60055
style DefaultModeYAxis fill:#2962FF55
style BButton fill:#AA00FF55
style XButton fill:#FF6D0055
style DefaultModeYButton fill:#00C85355
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.
flowchart
subgraph Local[Local]
PhysicalController[Physical Controller] --> ControllerBuddy[ControllerBuddy] --> VJoy[vJoy + Win32 / uinput] --> TargetApplication[Target Application]
end
flowchart LR
subgraph Server[Server]
PhysicalController[Physical Controller] --> ControllerBuddyServer[ControllerBuddy]
end
ControllerBuddyServer -. UDP .-> ControllerBuddyClient
subgraph Client[Client]
ControllerBuddyClient[ControllerBuddy] --> VJoy[vJoy + Win32 / uinput] --> TargetApplication[Target Application]
end
| 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.
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
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 |