ControllerBuddy-Flatpak
September 17, 2026 · View on GitHub
📖 Description
This repository provides the official Flatpak package for ControllerBuddy, the highly advanced game controller mapping application.
In addition to the application itself, the package includes:
- Official ControllerBuddy-Profiles located at
/app/share/ControllerBuddy-Profiles - Two helper scripts (
proton-wrapper.shanddosbox-wrapper.sh) to simplify integration with Proton and DOSBox Staging
⬇️ Installation
To install the ControllerBuddy Flatpak package, follow these steps:
-
Add the repository with the following command:
flatpak remote-add --if-not-exists ControllerBuddy https://flatpak.controllerbuddy.org/index.flatpakrepo -
Install the application by running:
flatpak install -y ControllerBuddy de.bwravencl.ControllerBuddy
📜 Wrapper Scripts
The package includes two scripts (proton-wrapper.sh and dosbox-wrapper.sh) located in /app/share/. These enable seamless integration between ControllerBuddy, Steam/Proton games, and DOSBox Staging.
Using these scripts is optional.
Important
Although these scripts are delivered via Flatpak, they are intended to run inside the Steam Linux Runtime (Proton) or directly on the host system (DOSBox), rather than within the ControllerBuddy Flatpak container itself.
⚛️ Proton Wrapper
The proton-wrapper.sh script automates the following steps:
- Ensures the Protontricks Flatpak is installed
- Disables native joysticks in the game's Proton prefix
- Updates the ControllerBuddy Flatpak
- Launches ControllerBuddy with the specified profile
- Ensures PowerShell is installed in the game's Proton prefix
- Runs the profile's configuration script within the game's Proton prefix
- Launches the game
- Shuts down ControllerBuddy when the game exits
To use it, add the following to the game's Launch Options in Steam (replace <profile.json> with the ControllerBuddy profile filename):
"$("$STEAM_RUNTIME"/scripts/switch-runtime.sh --runtime='' -- flatpak info -l de.bwravencl.ControllerBuddy)/files/share/proton-wrapper.sh" <profile.json> %command%
Important
The %command% argument must be appended as shown above.
Steam substitutes it with the actual launch command.
Definitions of environment variables can be added at the beginning of the line, if necessary.
📺 DOSBox Wrapper
The dosbox-wrapper.sh script automates the following steps:
- Updates the ControllerBuddy Flatpak
- Launches ControllerBuddy with the specified profile
- Forces DOSBox to use the ControllerBuddy virtual joystick
- Overrides mouse sensitivity in DOSBox if
mouse_sensitivityis provided - Launches DOSBox
- Shuts down ControllerBuddy when DOSBox exits
Call the script as follows:
"$(flatpak info -l de.bwravencl.ControllerBuddy)/files/share/dosbox-wrapper.sh" <profile.json> <dosbox.conf> [mouse_sensitivity]
Or, alternatively, as part of Launch Options in Steam, i.e., from within a Steam Runtime container:
IGNORE='%command%'; "$("$STEAM_RUNTIME"/scripts/switch-runtime.sh --runtime='' -- flatpak info -l de.bwravencl.ControllerBuddy)/files/share/dosbox-wrapper.sh" <profile.json> <dosbox.conf> [mouse_sensitivity]
| Argument | Description |
|---|---|
profile.json | Filename of the ControllerBuddy profile |
dosbox.conf | Path of the DOSBox configuration file |
mouse_sensitivity | Optional floating-point value setting the scale for mouse motion |