> 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/subsystems/input.md).

# Core Input

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

Core input turns logical input IDs into ability activation, press/release notifications, held input state, and input queues. It does not depend on Unity's Input System package.

## What It Does

| Type                         | Responsibility                                                     |
| ---------------------------- | ------------------------------------------------------------------ |
| `AbilityInputId`             | Stable logical input name such as `Ability1` or `TargetConfirm`.   |
| `AbilityInputLibrary`        | Project asset listing logical inputs and categories.               |
| `AbilityInputBindingSet`     | Actor/ability binding data.                                        |
| `AbilityInputQueue`          | Runtime queue and binding resolver owned by the ASC.               |
| `IAbilityInputSource`        | Interface for simple press/release sources.                        |
| `IAbilityInputContextSource` | Interface for sources that include `AbilityInputEventContext`.     |
| `AbilityInputEventContext`   | Input ID, state, timestamp, source, and optional external context. |

## When To Use It

Use core input whenever an ability should respond to a logical action instead of direct code activation. Use logical input even if you later bind it to keyboard, gamepad, mobile UI, AI, or Game Creator.

## Editor Setup

1. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
2. On `Setup`, create or assign `defaultInputLibrary`.
3. Select the `AbilityInputLibrary`.
4. Add categories such as `Abilities` and `Targeting`.
5. Add input names such as `Ability1`, `Ability2`, `TargetConfirm`, and `TargetCancel`.
6. On an actor or bootstrap asset, configure an `AbilityInputBindingSet`.
7. Bind each ability definition to an `AbilityInputId`.
8. Add an input source component or custom input source to dispatch press/release events.

Create path:

```
Assets > Create > Gameplay Ability Toolkit > Input > Ability Input Library
```

## Configuration Fields

| Asset or type                  | Field                  | Meaning                                               |
| ------------------------------ | ---------------------- | ----------------------------------------------------- |
| `AbilityInputLibrary`          | `Inputs`               | Logical input definitions.                            |
| `AbilityInputLibrary`          | `Categories`           | Editor grouping only.                                 |
| `AbilityInputDefinition`       | `InputName`            | C#-style identifier.                                  |
| `AbilityInputDefinition`       | `DisplayName`          | UI/editor display name.                               |
| `AbilityInputDefinition`       | `Category`             | Group in the input library.                           |
| `AbilityInputBindingSet.Entry` | Ability/input fields   | Binds one ability to one logical input.               |
| `AbilityInputQueue`            | Input layers           | Runtime override layers with priority and owner.      |
| `AbilityInputQueue`            | Consumers/interceptors | Runtime handlers that can observe or intercept input. |

## Runtime Flow

```mermaid
flowchart TD
    Source["Input source"] --> Queue["AbilityInputQueue"]
    Queue --> Held["Held input state"]
    Queue --> Bindings["Effective bindings"]
    Bindings --> Abilities["RuntimeAbilities.HandleInputPressed/Released"]
    Abilities --> Specs["Matching AbilitySpec"]
    Specs --> Activate["Activate, notify press, or notify release"]
    Queue --> Snapshots["Input snapshots for debug UI"]
```

## Input Layers

Input layers let temporary systems override or add bindings:

* A weapon stance can bind `Ability1` to a different attack.
* A vehicle can replace character actions.
* A tutorial can intercept input until a step is complete.

Use `AddInputLayer(bindingSet, priority, owner)` and dispose the returned handle or call `RemoveInputLayer(owner)` when leaving the mode.

## Consumers and Interceptors

Consumers observe input after dispatch. Interceptors can handle an input before normal ability activation. Use these sparingly:

* Targeting confirm/cancel.
* Tutorial gating.
* Modal gameplay interactions.
* Temporary UI selection modes.

## Debugging Checklist

* If input definitions do not show in drawers, validate `AbilityInputLibrary`.
* If input reaches the ASC but no ability activates, inspect `AbilityInputBindingSet`.
* If an ability activates on press unexpectedly, check `ActivateOnInputPressed`.
* If held state looks wrong, inspect the ASC `Inputs` tab.
* If a temporary mode keeps intercepting input, confirm the layer/interceptor handle is disposed.

## Common Mistakes

| Mistake                                     | Result                      | Fix                                  |
| ------------------------------------------- | --------------------------- | ------------------------------------ |
| Treating `AbilityInputId` as a keyboard key | Remapping becomes difficult | Keep physical input in a source/map. |
| Duplicate input names                       | Lookup ambiguity            | Run input library validation.        |
| Not unbinding custom input sources          | Duplicate events            | Unbind on disable/dispose.           |
| Long-lived high-priority input layer        | Base bindings never run     | Remove the layer when the mode ends. |

## Examples and Tests

* Tutorial: input binding for tutorial abilities.
* Arena Demo: player ability slots and targeting confirm/cancel.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Input/InputQueueContractTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Systems/InputTargetCueDeepTests.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/subsystems/input.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.