> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.playability.gg/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Map Inputs to Virtual Gamepad Actions

Gamepad actions let a compatible game receive PlayAbility input as a standard controller. Choose a digital action for an on/off control, or an analog action when the amount of movement should follow the trigger.

## Before you begin

- Load an editable profile.
- Confirm that the target game accepts controller input.
- Install the virtual-gamepad support required by your operating system:
  - **Windows:** ViGEmBus
  - **Linux:** `uinput` access and the bundled PlayAbility setup script
  - **macOS:** VirtualHIDGamepad

If PlayAbility cannot create the virtual controller, it displays a red alert at the bottom of the window.

## Choose the right gamepad action

- **Buttons:** A, B, X, Y, shoulder buttons, stick buttons, Back, Start, and Guide
- **D-Pad:** Up, Down, Left, or Right
- **Directional sticks:** A full on/off push of the left or right stick in one direction
- **Stick axes:** Proportional horizontal or vertical movement on the left or right stick
- **Triggers:** Left or right analog trigger

Use a directional stick action for a digital trigger such as a key, switch, voice command, or dwell target. Use a stick-axis action for smooth steering or aiming from an analog-capable input such as head motion, mouse motion, or a physical gamepad axis. Face gestures can also drive supported analog actions progressively.

## Map a gamepad button or direction

1. Open **Mapping** from the sidebar and confirm the intended profile is active.
2. Select **Add actions**.
3. Select **Gamepad**.
4. Select the button, D-Pad direction, or directional stick action you want.
5. Select the **Add** button showing the number of selected actions.
6. On the new row, select **Select a trigger**.
7. Choose an existing compatible trigger, or select **Create a new trigger +** and configure one.
8. Select an **Action Mode**:
   - **Default** keeps the action active while the trigger is active.
   - **Toggle** switches the action on or off with each activation.
   - **Short Press** sends a 100 ms press.
   - **Long Press** sends a 300 ms press.
   - **Double Press** or **Triple Press** sends repeated quick presses.
9. Select **Save**.

## Map an analog stick axis or trigger

1. Select **Add actions**, then open **Gamepad**.
2. Select the required left- or right-stick X or Y axis, or select **Left Trigger** or **Right Trigger**.
3. Add the action and select **Select a trigger**.
4. Choose an analog-capable trigger offered by the editor.
5. Configure its range, deadzone, sensitivity, threshold, or other settings as needed.
6. For a stick axis, use **Invert axis direction** if movement is reversed.
7. For an analog trigger, keep **Default** mode for progressive output. Other press modes produce digital press behavior.
8. Select **Save**.

Stick-axis actions do not use an Action Mode because their output follows a continuous value.

## Enable the virtual gamepad

1. Turn on **Main Output** with PlayAbility's play/pause control.
2. Confirm that **Gamepad Out** is active in the Controls area.
3. Resolve any red virtual-gamepad alert at the bottom of the window.
4. If you want the local virtual controller, open **Connections** and turn off **PlayAbility Receiver** and **8BitDo Micro** output.
5. Start or restart the game after the virtual controller is ready.

PlayAbility Receiver and 8BitDo Micro are alternative output routes. Enabling either one disconnects the local virtual gamepad.

## Verify the mapping

1. Start with a simple action such as the **A** button.
2. Activate its trigger and confirm that the mapping's live feedback changes.
3. Confirm that **Main Output** and **Gamepad Out** remain enabled.
4. Test the action in a game that accepts controller input.
5. For an axis or trigger, move through its full usable range and confirm that the response is smooth and returns to neutral.

## Troubleshooting and limitations

### A red virtual-gamepad alert is shown

- On Windows, select **Run ViGEm installer**, allow PlayAbility to close, finish the installation, and reopen it.
- On Linux, open **Gamepads**, run the bundled setup script using the exact path shown, and restart PlayAbility.
- On macOS, install and activate VirtualHIDGamepad, then restart PlayAbility.

### The mapping responds but the game receives nothing

- Confirm the correct profile is active.
- Turn on **Main Output** and **Gamepad Out**.
- Disable PlayAbility Receiver or 8BitDo Micro output when you intend to use the local virtual controller.
- Check any foreground-app output rules.
- Restart games that scan for controllers only at launch.

### Movement is always fully on

You selected a directional stick action. Replace it with the matching X or Y stick-axis action and choose an analog-capable trigger.

### An axis or trigger is reversed or too sensitive

Edit the mapping. Invert the axis if needed, then adjust the input's range, deadzone, threshold, and maximum sensitivity.

### A gamepad action remains active

Run **Release All**. Then use **Default** or a press mode instead of **Toggle** if the action should not remain latched.

### The game still ignores the controller

PlayAbility can create the virtual device, but individual games decide which controller APIs and devices they accept. Test another controller-aware application to separate a PlayAbility output problem from a game-specific detection problem.

## Related articles

- [Build and Edit a Mapping](https://help.playability.gg/en/article/build-and-edit-a-mapping-u0q0bs/)
- [Troubleshoot Virtual Controller Output](https://help.playability.gg/en/article/troubleshoot-virtual-controller-output-2hf6eq/)
- [Set Up the PlayAbility Adaptive Receiver](https://help.playability.gg/en/article/set-up-the-playability-adaptive-receiver-3ray5q/)
- [Use PlayAbility on Xbox through Remote Play or Cloud Gaming](https://help.playability.gg/en/article/use-playability-on-xbox-through-remote-play-or-cloud-gaming-1jxvveh/)