Articles on: Troubleshooting

Troubleshoot Virtual Controller Output

PlayAbility presents a standard virtual gamepad to PC games. Use this guide to separate a driver problem from an output, profile, connector, or game-detection problem.


Quick checks


  1. Load a profile that contains at least one gamepad action.
  2. Enable Main Output using the play/pause control in PlayAbility.
  3. Confirm that Gamepad Out is active in the Controls area.
  4. Open Connections and turn off PlayAbility Receiver and 8BitDo Micro output if you intend to use the local virtual gamepad.
  5. Look for a red virtual-gamepad alert at the bottom of the PlayAbility window.
  6. If no alert is present, close and reopen the game after PlayAbility is ready.


The PlayAbility Receiver and 8BitDo Micro are alternative output routes. While either route is enabled, the local virtual gamepad on the computer is disconnected by design.


Repair the driver on Windows


Use these steps when the alert says PlayAbility could not connect to the ViGEm Bus driver or could not create the virtual gamepad.


  1. In the alert at the bottom of PlayAbility, select Run ViGEm installer.
  2. Allow PlayAbility to close and complete the driver installation.
  3. Reopen PlayAbility after the installer finishes.
  4. Load your profile and enable Main Output.
  5. Confirm that the red alert no longer appears.


If the bundled installer cannot start, use the ViGEmBus installer in the PlayAbility installation folder or install ViGEmBus from its official release source. Restart PlayAbility after installation.


Repair the driver on Linux


PlayAbility uses uinput for its Linux virtual gamepad.


  1. Select Gamepads in the PlayAbility sidebar.
  2. Find the Linux setup needed for the virtual gamepad message.
  3. Select Show setup script in folder.
  4. Open a terminal and run the shown script with Bash. Use the exact path displayed by PlayAbility.
  5. Approve the administrator prompt so the script can install the required udev rules and load uinput.
  6. Restart PlayAbility.
  7. If PlayAbility still reports missing or incomplete udev rules, reboot once and test again.


On immutable or unusually configured Linux distributions, consult the distribution documentation if the bundled script cannot install persistent udev rules.


Repair the driver on macOS


PlayAbility uses the VirtualHIDGamepad DriverKit driver on macOS.


  1. Install the VirtualHIDGamepad driver if it is not installed.
  2. Open its companion application and activate the driver.
  3. Restart PlayAbility.
  4. Confirm that the virtual-gamepad alert no longer appears.


Verify the repair


  1. Load a profile with a simple gamepad mapping, such as a trigger mapped to the A button.
  2. Enable Main Output and Gamepad Out.
  3. Activate the trigger.
  4. Confirm that the mapping’s live feedback changes.
  5. Open or restart the target game and confirm that it responds to the virtual controller.


A cleared alert confirms that PlayAbility created the virtual device. Testing an action in the target game confirms the full path from mapping to game.


If there is no driver alert but the game does not respond


Check these items in order:


  1. Active profile: Make sure the profile containing the mapping is loaded.
  2. Mapped action: Verify that the mapping outputs a gamepad button, stick, D-pad direction, or trigger—not only a keyboard or mouse action.
  3. Main Output: The main play/pause control must show output enabled.
  4. Gamepad Out: This output must be active for local virtual-gamepad actions.
  5. Foreground-app rules: If you configured automatic output allow/block lists, confirm that the current game is allowed. Main Output can be on while foreground-app gating blocks effective output.
  6. Alternative connectors: Disable PlayAbility Receiver or 8BitDo Micro output to restore the local virtual gamepad.
  7. Game launch order: Some games only scan for controllers when they start. Leave PlayAbility running, then restart the game.
  8. Stuck state: Run Release All, then try the mapping again.


Alert-specific guidance


  • Could not connect to ViGEm Bus: Install or repair ViGEmBus on Windows, then restart PlayAbility.
  • Could not open the Linux virtual gamepad (uinput): Run the setup script from the Gamepads page and check /dev/uinput permissions.
  • Could not connect to the VirtualHID gamepad driver: Install or activate VirtualHIDGamepad on macOS, then restart PlayAbility.
  • Virtual gamepad module is not available in this app build: Reinstall a packaged PlayAbility build for your operating system. A build without the native module cannot create the device.
  • The virtual gamepad could not start after several attempts: Restart PlayAbility after confirming the platform driver is installed and active.
  • Could not finish creating the virtual gamepad: Recheck the platform driver setup and make sure alternative serial or HID output is disabled.


Limitations


  • The local virtual gamepad is supported on Windows, Linux, and macOS through different platform drivers.
  • A keyboard or mouse output problem is not necessarily a virtual-gamepad driver problem. Test the output type used by the mapping.
  • PlayAbility Receiver and 8BitDo Micro intentionally replace the local virtual-gamepad route while enabled.
  • Dismissing the red alert hides that occurrence; it does not repair the driver.

Updated on: 29/07/2026