> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/unity-input-system.md).

# Unity Input System

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/unity-input-system?fallback=true>

The Unity Input System integration maps Unity `InputActionReference` objects to core logical input IDs. It is optional; the core input subsystem works without it.

This bridge does not change ability activation rules. It only converts Unity Input System action events into toolkit `AbilityInputId` press/release events.

## What It Does

| Type                             | Responsibility                                                                            |
| -------------------------------- | ----------------------------------------------------------------------------------------- |
| `InputSystemAbilityInputMap`     | ScriptableObject mapping `AbilityInputId` to `InputActionReference`.                      |
| `InputSystemAbilityInputBinding` | One logical input/action binding row.                                                     |
| `InputSystemAbilityInputSource`  | Scene component that listens to Unity input actions and dispatches ability input events.  |
| Input Dashboard page             | Creates/selects input maps, adds/configures input sources, and displays ASC binding rows. |

## When To Use It

Use this integration when your project already uses Unity's Input System package and you want keyboard, gamepad, or action-map events to activate abilities.

Do not use it for AI-only actors or server-side simulation. Those can call core input or ability APIs directly.

## Editor Setup

1. Install and enable the Unity Input System package.
2. Create a Unity Input Actions asset with actions for your ability buttons.
3. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
4. Select the `Input` page.
5. In `Global Setup`, create or select `GASConfiguration`.
6. Create or select `AbilityInputLibrary`.
7. Confirm `Target Confirm` and `Target Cancel` are set.
8. Select a GameObject with `AbilitySystemComponent`.
9. In `Unity Input System`, create or select an `InputSystemAbilityInputMap`.
10. Add bindings from logical inputs to `InputActionReference` objects.
11. Click `Add` or `Configure` for `InputSystemAbilityInputSource`.
12. Enter Play Mode and inspect `Inspector > AbilitySystemComponent > Inputs`.

Create path:

```
Assets > Create > Gameplay Ability Toolkit > Input > Input System Ability Input Map
```

## Configuration Fields

### InputSystemAbilityInputMap

| Field                     | Meaning                                                   |
| ------------------------- | --------------------------------------------------------- |
| `InputBinds`              | List of logical input to `InputActionReference` bindings. |
| Binding `Input`           | `AbilityInputId` from the logical input library.          |
| Binding `ActionReference` | Unity Input System action reference.                      |

Only bindings with a non-empty input name and a valid action reference are used at runtime.

### InputSystemAbilityInputSource

| Field           | Meaning                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `AbilitySystem` | Target actor ASC. Auto-filled from the same GameObject on reset/enable if missing.                    |
| `InputAsset`    | `InputSystemAbilityInputMap`.                                                                         |
| `BindOnEnable`  | Automatically binds/unbinds this source to the ASC input queue.                                       |
| `EnableActions` | Enables referenced actions while the component is enabled and disables actions it enabled on cleanup. |

## Runtime Flow

```mermaid
flowchart TD
    UnityAction["Unity InputAction performed/canceled"] --> Source["InputSystemAbilityInputSource"]
    Source --> Event["AbilityInputEventContext"]
    Event --> Queue["ASC AbilityInputQueue"]
    Queue --> RuntimeAbilities["RuntimeAbilities"]
    RuntimeAbilities --> Ability["Input-bound AbilitySpec"]
```

`performed` dispatches `InputState.Pressed`. `canceled` dispatches `InputState.Released`.

## Debugging Checklist

* If actions never fire, confirm the Unity Input Actions asset is enabled and the action map is active.
* If the action fires but ASC input does not update, confirm `InputSystemAbilityInputSource.AbilitySystem`.
* If the ASC sees input but no ability activates, confirm the ability has an input binding in the ASC initial inputs or runtime binding.
* If targeting confirm/cancel does not work, confirm those logical inputs exist and are mapped to actions.
* If input events duplicate, check for multiple input source components bound to the same ASC.

## Common Mistakes

| Mistake                                            | Result                          | Fix                                                                           |
| -------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |
| Mapping keyboard keys directly in ability assets   | Abilities are not remappable    | Use `AbilityInputId` in ability bindings and map actions in this integration. |
| Forgetting `BindOnEnable` and not binding manually | Source fires but ASC ignores it | Enable `BindOnEnable` or call `BindInputSource`.                              |
| Sharing one input map with missing actions         | Some inputs silently skip       | Inspect `ValidBindings` through the map inspector.                            |
| Letting another system disable actions             | Input stops mid-game            | Coordinate action map ownership.                                              |

## Examples and Tests

* Dashboard Input page is the recommended editor entry point.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/InputSystem.Tests/Editor/InputSystemIntegrationTests.cs`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/unity-input-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.