{"id":35171164,"url":"https://github.com/bwravencl/controllerbuddy","last_synced_at":"2026-04-02T17:10:58.559Z","repository":{"id":21206264,"uuid":"24519074","full_name":"bwRavencl/ControllerBuddy","owner":"bwRavencl","description":"A game controller mapping tool crafted specifically for flight simulators","archived":false,"fork":false,"pushed_at":"2026-02-21T01:40:57.000Z","size":80307,"stargazers_count":155,"open_issues_count":5,"forks_count":11,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-02-21T07:37:41.001Z","etag":null,"topics":["controller-mapping","dcs-world","dinput","dualsense","dualshock","falcon-bms","flight-simulator","game-controller","gamepad","gamepad-mapping","hotas","il-2","input-profiles","java","remote-control","steamdeck","vjoy","xbox-controller","xinput"],"latest_commit_sha":null,"homepage":"https://controllerbuddy.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bwRavencl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://controllerbuddy.org/donate"}},"created_at":"2014-09-27T00:04:46.000Z","updated_at":"2026-02-21T01:37:24.000Z","dependencies_parsed_at":"2023-09-22T10:03:43.286Z","dependency_job_id":"fa9f8ee0-a17a-414e-8326-f71bbb1127b6","html_url":"https://github.com/bwRavencl/ControllerBuddy","commit_stats":null,"previous_names":[],"tags_count":1408,"template":false,"template_full_name":null,"purl":"pkg:github/bwRavencl/ControllerBuddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwRavencl%2FControllerBuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwRavencl%2FControllerBuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwRavencl%2FControllerBuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwRavencl%2FControllerBuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bwRavencl","download_url":"https://codeload.github.com/bwRavencl/ControllerBuddy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwRavencl%2FControllerBuddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29946463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T17:57:52.716Z","status":"ssl_error","status_checked_at":"2026-02-28T17:57:31.974Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["controller-mapping","dcs-world","dinput","dualsense","dualshock","falcon-bms","flight-simulator","game-controller","gamepad","gamepad-mapping","hotas","il-2","input-profiles","java","remote-control","steamdeck","vjoy","xbox-controller","xinput"],"created_at":"2025-12-28T20:50:28.213Z","updated_at":"2026-04-02T17:10:58.550Z","avatar_url":"https://github.com/bwRavencl.png","language":"Java","readme":"# ControllerBuddy\n\n\u003c!--suppress HtmlDeprecatedAttribute --\u003e\n\u003cimg src=\"icon/icon.svg\" alt=\"ControllerBuddy Logo\" align=\"right\" width=\"128px\"/\u003e\n\n[![ControllerBuddy Release Status](https://github.com/bwRavencl/ControllerBuddy/actions/workflows/release.yml/badge.svg)](https://github.com/bwRavencl/ControllerBuddy/actions/workflows/release.yml)\n\nVisit the [ControllerBuddy Homepage](https://controllerbuddy.org) to get started.  \nJoin the [ControllerBuddy Discord](https://discord.gg/2Sg9ggZrAp) for support and community discussions.\n\n## 📖 Description\n\nControllerBuddy is an advanced gamepad mapping software that supports the creation of input profiles for complex target applications such as flight simulators.\n\nIn 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).\n\nThe 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.\n\n## ⬇️ Download and Installation\n\n### 📜 Install-Script\n\nFor the easiest way to install and update, use the [ControllerBuddy-Install-Script](https://github.com/bwRavencl/ControllerBuddy-Install-Script).  \nIt automates all the steps below and much more!\n\n### 📦 Flatpak\n\nLinux users may want to use the [ControllerBuddy-Flatpak](https://github.com/bwRavencl/ControllerBuddy-Flatpak).\n\n### 🧑‍🔧 Manual Installation\n\n#### 🪟 Windows x86-64\n\n1. First download and install [vJoy 2.2.2.0](https://github.com/BrunnerInnovation/vJoy/releases/tag/v2.2.2.0) on your system.\n2. [Click here](https://github.com/bwRavencl/ControllerBuddy/releases/latest) and download the latest build of ControllerBuddy for Windows as a ZIP archive.\n3. Extract the `ControllerBuddy` directory from the archive to any desired location on your hard-drive.\n4. Run `ControllerBuddy.exe` inside the extracted `ControllerBuddy` directory.\n\n#### 🐧 Linux x86-64 / aarch64\n\n1. Allow access to uinput:\n    ```sh\n    echo 'KERNEL==\"uinput\", SUBSYSTEM==\"misc\", TAG+=\"uaccess\", OPTIONS+=\"static_node=uinput\"' | sudo tee /etc/udev/rules.d/60-controllerbuddy.rules\n    ```\n2. Load the uinput kernel module at boot:\n    ```sh\n    echo uinput | sudo tee /etc/modules-load.d/controllerbuddy.conf\n    ```\n3. Reboot\n4. [Click here](https://github.com/bwRavencl/ControllerBuddy/releases/latest) and download the latest build of ControllerBuddy for Linux as a TGZ archive.\n5. Extract the `ControllerBuddy` directory from the archive to any desired location on your hard-drive.\n6. Run `ControllerBuddy` inside the extracted `ControllerBuddy/bin` directory.\n\n## ✨ Features\n\n### 🧬 Core Capabilities\n\nControllerBuddy maps physical inputs to **Actions**, such as moving a virtual joystick axis, triggering a keystroke, or moving the mouse cursor.  \nMappings are organized into **Modes** - distinct functional layers activated or toggled at the press of a button.\n\n* **Mode Switching:** Swap entire mapping layouts dynamically on the fly using toggle or momentary buttons to multiply the total number of available functions on your controller.\n* **Virtual Joystick Control:** Map inputs to virtual buttons and axes, including the ability to reset axes to specific preconfigured positions.\n* **Relative Axis Mapping:** Solves the challenge of mapping persistent controls to self-centering sticks. A relative axis maintains its value even after the physical stick is released - ideal for stable control over **throttle** or **camera angles**.\n* **Keyboard \u0026 Mouse Emulation:** Full support for keystrokes (including modifiers), mouse buttons, cursor movement, and scrolling.\n* **Action Cycles:** Sequence multiple sub-actions that trigger one after another with each press.\n* **On-Screen Keyboard:** A gamepad-driven virtual keyboard that allows for the input of keystrokes and combinations without a requiring a physical keyboard.\n\n### 👤 User Experience\n\n* **Profile Management:** Create, save, and switch between custom mapping profiles for different games or apps.\n* **Powerful UI:** A fast, clean and intuitive interface with full support for **light and dark themes**.\n* **In-Game Overlay:**\n    * Monitor the currently active **Mode**.\n    * Visualize the current position of **virtual axes**.\n* **Localization:** Fully localized in **English** and **German**.\n\n### ⚙️ Modes of Operation\n\nControllerBuddy can be used as a standalone local tool or distributed over a network:\n\n* **Local:** Standard low-latency operation on a single machine.\n* **Client-Server:** Send controller inputs across a network.\n\n### 🔌 Controller \u0026 OS Support\n\n* **Gamepad Compatibility:**\n    * **Xbox Series X|S**, **Xbox One**, and **Xbox 360 Controllers**\n    * **DualSense (PS5)** and **DualShock 3/4 (PS3/PS4)** controllers\n    * **Many more** via the [SDL GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB) project.\n* **Operating Systems:**\n    * **Windows \u0026 Linux:** Full support (Local, Client, and Server).\n    * **macOS:** Server-only support (no binaries provided).\n\n## 🗃️ Profiles\n\n### 🧩 Definitions\n\n**Profiles** are JSON-based configuration files that tailor ControllerBuddy to specific games.\nOnce loaded, they can be edited and saved through the built-in interface.\n\nTo manage complex setups, Profiles organize your input mappings into **Modes**. Think of Modes as different **layers or \"shift-states\"** for your controller.\n\nWithin each Mode, you can map an axis or button to one or more **Actions**.  \nBy assigning different Actions to the same control across multiple Modes, you enable ControllerBuddy to instantly remap your controller as you switch between layers.\n\n\u003e [!TIP]\n\u003e The [ControllerBuddy-Profiles](https://github.com/bwRavencl/ControllerBuddy-Profiles) repository contains a vast collection of official profiles for many different flight simulators.\n\n### 🗺️ Structure\n\nThe general structure of a Profile looks as follows:\n\n```mermaid\nflowchart LR\n    Profile[(\"Profile (.json file)\")] ---- DefaultMode\n    Profile --- BButton(B Button) \u0026 XButton(X Button)\n    BButton --\u003e BButtonModeAction[/Mode Action/] -. switch to .-\u003e ModeA\n    XButton --\u003e XButtonModeAction[/Mode Action/] -. switch to .-\u003e ModeB\n    subgraph DefaultMode[Default Mode]\n        direction LR\n        DefaultModeXAxis(X Axis) --\u003e DefaultModeXAxisAction1[/Action 1/] \u0026 DefaultModeXAxisAction2[/Action 2/]\n        DefaultModeYAxis(Y Axis) --\u003e DefaultModeYAxisAction[/Action/]\n        DefaultModeAButton(A Button) --\u003e DefaultModeAButtonAction1[/Action 1/] \u0026 DefaultModeAButtonAction2[/Action 2/]\n        DefaultModeYButton(Y Button) --\u003e CycleAction[/Cycle Action/] -. perform next .-\u003e CycleActions\n        DefaultModeXAxis ~~~ CycleAction\n        DefaultModeYAxis ~~~ CycleAction\n        DefaultModeAButton ~~~ CycleAction\n        DefaultModeYButton ~~~ CycleAction\n        subgraph CycleActions[Cycle]\n            CycleAction1[/Action 1/] --\u003e CycleAction2[/Action 2/] --\u003e CycleAction3[/Action 3/] --\u003e CycleAction1\n        end\n    end\n    subgraph ModeA[Mode A]\n        direction LR\n        ModeAXAxis(X Axis) --\u003e ModeAXAxisAction[/Action/]\n        ModeAAButton(A Button) --\u003e ModeAAButtonAction[/Action/]\n    end\n    subgraph ModeB[Mode B]\n        direction LR\n        ModeBXAxis(X Axis) --\u003e ModeBXAxisAction1[/Action 1/] \u0026 ModeBXAxisAction2[/Action 2/]\n    end\n    style DefaultModeXAxis fill:#D5000055\n    style ModeAXAxis fill:#D5000055\n    style ModeBXAxis fill:#D5000055\n    style DefaultModeAButton fill:#FFD60055\n    style ModeAAButton fill:#FFD60055\n    style DefaultModeYAxis fill:#2962FF55\n    style BButton fill:#AA00FF55\n    style XButton fill:#FF6D0055\n    style DefaultModeYButton fill:#00C85355\n```\n\n### ⛓️ Mode Inheritance\n\nWhen switching between Modes, **any axes or buttons not explicitly redefined will inherit their behavior from the previously active Mode**.  \nThis inheritance persists across multiple Mode levels, as illustrated by the following example:\n\n**Default Mode** (Base) → **Mode A** (Layer 1) → **Mode B** (Layer 2)  \n*If an axis or button is not mapped in **Mode B**, ControllerBuddy checks **Mode A**, and finally the **Default Mode**.*\n\n### 🔀 Switching Behaviors\n\nTwo different switching behaviors can be configured:\n\n- **Momentary (Default):** The Mode remains active only while the button is held (similar to a **Shift key**).\n- **Toggle:** Press once to activate, press again to deactivate (similar to **Caps Lock**).\n\n## 🏛️ Architecture\n\n### 🏠 Local Mode\n\n```mermaid\nflowchart\n    subgraph Local[Local]\n        PhysicalController[Physical Controller] --\u003e ControllerBuddy[ControllerBuddy] --\u003e VJoy[vJoy + Win32 / uinput] --\u003e TargetApplication[Target Application]\n    end\n```\n\n### 🌐 Client-Server Mode\n\n```mermaid\nflowchart LR\n    subgraph Server[Server]\n        PhysicalController[Physical Controller] --\u003e ControllerBuddyServer[ControllerBuddy]\n    end\n    ControllerBuddyServer -. UDP .-\u003e ControllerBuddyClient\n    subgraph Client[Client]\n        ControllerBuddyClient[ControllerBuddy] --\u003e VJoy[vJoy + Win32 / uinput] --\u003e TargetApplication[Target Application]\n    end\n```\n\n## 🖼️ Screenshots\n\n![Modes Tab](screenshots/screenshot_1.png)\n\n![Assignments Tab](screenshots/screenshot_2.png)\n\n![Component Editor - Button](screenshots/screenshot_3.png)\n\n![Component Editor - Axis](screenshots/screenshot_4.png)\n\n![Dark Mode](screenshots/screenshot_5.png)\n\n![Visualization Tab](screenshots/screenshot_6.png)\n\n![Overlay](screenshots/screenshot_7.png)\n\n## ⌨️ Command Line Parameters\n\n| Parameter             | Arguments               | Description                                                                                                | Available for scripting |\n|-----------------------|-------------------------|------------------------------------------------------------------------------------------------------------|:-----------------------:|\n| `‑autostart`          | local / client / server | starts the specified mode of operation after launch                                                        |           yes           |\n| `‑export`             | file destination        | exports a visualization of the current profile to the specified path                                       |           yes           |\n| `‑gamecontrollerdb`   | file source             | adds the SDL controller mappings from the specified [file](https://github.com/mdqinc/SDL_GameControllerDB) |           yes           |\n| `‑help`               |                         | prints the help and exits                                                                                  |           no            |\n| `-host`               | hostname / IP address   | sets the host address for outgoing network connections                                                     |           yes           |\n| `-password`           | password                | sets the password for all network connections                                                              |           yes           |\n| `-port`               | port number             | sets the server port for all network connections                                                           |           yes           |\n| `‑profile`            | file source             | loads the specified profile after launch                                                                   |           yes           |\n| `‑quit`               |                         | quits the application                                                                                      |           yes           |\n| `‑save`               | file destination        | save the current profile to the specified path                                                             |           yes           |\n| `‑skipMessageDialogs` |                         | skips all message dialogs                                                                                  |           no            |\n| `-timeout`            | timeout in milliseconds | sets the timeout in milliseconds for all network connections                                               |           yes           |\n| `‑tray`               |                         | launches the application to the system tray                                                                |           yes           |\n| `‑version`            |                         | prints the version information and exits                                                                   |           no            |\n\nIf ControllerBuddy is already running, launching a **second instance** with any of the above parameters marked as *available for scripting* **will forward the specified action to the first instance** and then exit immediately.\n\nThis powerful mechanism allows seamless integration of ControllerBuddy into third-party applications.  \nFor an example, see [ControllerBuddy-DCS-Integration](https://github.com/bwRavencl/ControllerBuddy-DCS-Integration), which demonstrates how ControllerBuddy can be integrated into [DCS World](https://www.digitalcombatsimulator.com).\n\n## 🙏 Attribution\n\nControllerBuddy makes use of these awesome software technologies and libraries:\n\n| Category             | Technologies                                                                                                                                                                                                                                           |\n|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Runtime \u0026 Build**  | [Azul Zulu](https://www.azul.com), [Gradle](https://gradle.org)                                                                                                                                                                                        |\n| **Input \u0026 Hardware** | [LWJGL](https://www.lwjgl.org), [SDL](https://libsdl.org), [SDL\\_GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB)                                                                                                                     |\n| **UI \u0026 Graphics**    | [FlatLaf](https://www.formdev.com/flatlaf), [JSVG](https://github.com/weisJ/jsvg)                                                                                                                                                                      |\n| **Utilities**        | [Apache Commons CLI](https://commons.apache.org/proper/commons-cli), [ClassGraph](https://github.com/classgraph/classgraph), [dbus-java](https://hypfvieh.github.io/dbus-java), [Gson](https://github.com/google/gson), [SLF4J](https://www.slf4j.org) |\n| **Code Quality**     | [CleanThat](https://github.com/solven-eu/cleanthat), [Error Prone](https://errorprone.info), [Spotbugs](https://spotbugs.github.io)                                                                                                                    |\n| **Code Formatting**  | [Eclipse JDT](https://projects.eclipse.org/projects/eclipse.jdt), [Eclipse WTP](https://projects.eclipse.org/projects/webtools), [ktfmt](https://facebook.github.io/ktfmt), [Spotless](https://github.com/diffplug/spotless)                           |\n| **Testing**          | [JUnit](https://junit.org), [Mockito](https://mockito.org)                                                                                                                                                                                             |\n\n## 🛠️ Building\n\nIf you want to build ControllerBuddy from source, this section might be helpful to get you started.  \nControllerBuddy uses the Gradle build system, the following Gradle tasks are supported:\n\n| Task                                   | Command                     |\n|----------------------------------------|-----------------------------|\n| Generate `Constants.java` source file  | `gradlew generateConstants` |\n| Run all checks                         | `gradlew check`             |\n| Apply Spotless formatting              | `gradlew spotlessApply`     |\n| Run ControllerBuddy                    | `gradlew run`               |\n| Run all tests                          | `gradlew test`              |\n| Generate test coverage report          | `gradlew jacocoTestReport`  |\n| Install a jpackage image               | `gradlew installDist`       |\n| Create a ZIP-compressed jpackage image | `gradlew distZip`           |\n| Create a TGZ-compressed jpackage image | `gradlew distTar`           |\n| Delete build and gen directories       | `gradlew clean`             |\n\n## ⚖️ License\n\n[GNU General Public License v3.0](LICENSE)\n","funding_links":["https://controllerbuddy.org/donate"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwravencl%2Fcontrollerbuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbwravencl%2Fcontrollerbuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwravencl%2Fcontrollerbuddy/lists"}