> 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-buffering.md).

# Input Buffering

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

Input buffering retries failed input activations for a short time. It is useful for responsive action games where a player presses an ability slightly before cooldown, cost, or tag requirements become valid.

![Practical input buffering diagram showing failed activation entering a pending queue and retrying.](/files/axeIqmk0EcZUrZpHxID5)

## What It Does

| Type                               | Responsibility                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| `AbilityActivationBufferSettings`  | Loads global/default buffer settings.                                                  |
| `AbilityActivationBufferProfile`   | ScriptableObject containing retry rules.                                               |
| `AbilityActivationBufferRule`      | One ability/input/failure/window rule.                                                 |
| `AbilityActivationBufferComponent` | Actor component that listens for input activation failures and retries matching specs. |

## When To Use It

Use input buffering for:

* Dodge shortly before recovery ends.
* Combo follow-ups.
* Ability presses during a short cooldown remainder.
* Button presses while a blocking tag is about to clear.

Avoid input buffering when the design requires exact timing or when queued actions would feel surprising.

## Editor Setup

1. Create a profile with `Assets > Create > Gameplay Ability Toolkit > Input > Ability Activation Buffer Profile`.
2. Add one rule per buffered ability or ability/input pair.
3. Assign the ability.
4. Optionally assign a specific logical input.
5. Set `Buffer Window`.
6. Choose whether to keep the buffered activation after release.
7. Select retryable failure reasons.
8. Add `AbilityActivationBufferComponent` to the actor.
9. Assign the actor ASC and profile.

## Configuration Fields

| Field               | Meaning                                                                           |
| ------------------- | --------------------------------------------------------------------------------- |
| `ability`           | Ability definition this rule applies to.                                          |
| `input`             | Optional logical input restriction. Empty means any input for that ability.       |
| `bufferWindow`      | Seconds the failed activation remains retryable.                                  |
| `keepAfterRelease`  | If false, releasing input clears the pending retry.                               |
| `retryableFailures` | Failure reasons that can be retried: cooldown, cost, tag requirements, or others. |

## Runtime Flow

```mermaid
flowchart TD
    Press["Input press"] --> Try["Try activate ability"]
    Try -->|success| Active["Ability active"]
    Try -->|failure| Failure["EventInputActivationFailed"]
    Failure --> Rule["Find matching buffer rule"]
    Rule --> Pending["Store pending activation"]
    Pending --> Tick["Tick until window expires"]
    Tick --> Retry["RetryActivateInputSpec"]
    Retry -->|success| Active
    Retry -->|still blocked| Pending
    Pending --> Expire["Expire, release, remove ability, or binding changed"]
```

## Practical Usage Patterns

| Design                      | Suggested rule                                                                    |
| --------------------------- | --------------------------------------------------------------------------------- |
| Dodge after attack recovery | Ability = Dodge, failure = TagRequirements, window = 0.20s.                       |
| Combo chain                 | Ability = next combo step, failure = TagRequirements, keep after release = false. |
| Cooldown comfort            | Ability = skill, failure = Cooldown, window = 0.15s.                              |
| Resource recovery           | Ability = ability, failure = Cost, window = short and clearly communicated.       |

## Debugging Checklist

* If buffering never happens, confirm the failure is an input activation failure, not direct code activation.
* If retries never succeed, inspect the original failure reason.
* If the pending entry disappears on release, check `keepAfterRelease`.
* If the wrong ability buffers, set the optional `input` field or split rules.
* If an ability was removed or rebound, pending entries for that spec are cleared automatically.

## Common Mistakes

| Mistake                         | Result                                 | Fix                                         |
| ------------------------------- | -------------------------------------- | ------------------------------------------- |
| Long buffer windows             | Actions fire late and surprise players | Keep windows short.                         |
| Buffering non-input activations | No retry event                         | Use input activation or custom retry logic. |
| Buffering every failure reason  | Invalid actions may fire later         | Limit retryable reasons.                    |
| Forgetting the component        | Profile exists but does nothing        | Add `AbilityActivationBufferComponent`.     |

## Examples and Tests

* Use Arena action timing as a reference for responsive abilities.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Input.Buffering.Tests/Editor/AbilityActivationBufferContractTests.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-buffering.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.