> 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/ability-system-component.md). # AbilitySystemComponent > Online doc: `AbilitySystemComponent` is the actor-level runtime owner. Attach one to every character, projectile owner, interactable, or combat object that needs gameplay tags, attributes, effects, abilities, or ability input. ![AbilitySystemComponent runtime orchestration.](/files/PpRpOKfcMEtuPIly6kvX) ## What It Does `AbilitySystemComponent` coordinates these runtime subsystems for one GameObject: | Subsystem | Runtime entry point | Responsibility | | ---------- | ------------------- | ------------------------------------------------------------------------------- | | Tags | `RuntimeTags` | Owned gameplay tags, tag counts, tag change events. | | Attributes | `RuntimeAttributes` | Base/current values, modifiers, clamping, derived values, change hooks. | | Effects | `RuntimeEffects` | Active effect specs, duration/periodic ticking, stacking, inhibition, removal. | | Abilities | `RuntimeAbilities` | Granted ability specs, activation, commit, cancellation, triggers, events. | | Input | `AbilityInputQueue` | Logical input binding, held input state, input layers, consumers, interceptors. | The component also exposes aggregate events such as `EventTagsChanged`, `EventAttributesChanged`, `EventEffectsChanged`, `EventAbilityActivated`, `EventAbilityEnded`, and `EventAbilityActivationFailed`. UI and editor tooling should prefer these aggregate events when they only need to refresh display state. ## When To Use It Use an ASC when the object needs any of these capabilities: | Scenario | ASC required? | Reason | | -------------------------------------------------- | ---------------------------------- | ------------------------------------------- | | A player has health, stamina, buffs, and abilities | Yes | The player owns state and activation rules. | | An enemy receives damage and status effects | Yes | Effects need a target ASC. | | A projectile only carries collision data | Usually no | The source ASC can apply the effect on hit. | | A pickup grants a buff when collected | Usually no | It can call into the collector's ASC. | | A world object has lock/unlock tags | Yes if tags are queried at runtime | Owned tags live on an ASC. | ## Required Assets and Components An actor setup normally includes: | Unity object | Required? | Notes | | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- | | `AbilitySystemComponent` | Yes | Add to the actor GameObject. | | Initial `AttributeSet` assets | Common | Add to `Initial Attributes` on the ASC. | | Initial `EffectDefinition` assets | Optional | Applied automatically during initialization. | | `AbilityInputBindingSet` | Optional | Grants logical input bindings at startup. | | `IAttributeChangeHook` components | Optional | Attach to the same GameObject for actor-scoped attribute hooks. | | Input source component | Optional | Use [Unity Input System](/docs/gameplay-ability-toolkit/integrations/unity-input-system.md) or custom `IAbilityInputSource`. | ## Editor Setup 1. Select the actor GameObject. 2. In the Inspector, click `Add Component`. 3. Add `AbilitySystemComponent`. 4. In `Initial Attributes`, add one or more `AttributeSet` assets. 5. In `Initial Effects`, add startup passives or default states only if they should apply as soon as the actor initializes. 6. In `Initial Inputs`, bind abilities to logical input IDs if this actor starts with input-driven abilities. 7. Enter Play Mode and keep the actor selected. 8. Inspect the runtime tabs in the ASC Inspector: `Attributes`, `Tags`, `Abilities`, `Effects`, `Inputs`, and `Events`. > Warning: Do not create multiple ASCs on one actor unless you are deliberately modeling separate independent gameplay owners. Most gameplay code assumes one ASC is the actor authority. ## Runtime Flow ```mermaid flowchart TD Awake["Awake or first property access"] --> Init["EnsureInitialized"] Init --> Tags["Create RuntimeTags"] Init --> Attrs["Create RuntimeAttributes from Initial Attributes"] Init --> Effects["Create RuntimeEffects"] Init --> Abilities["Create RuntimeAbilities"] Init --> Input["Create AbilityInputQueue"] Init --> Startup["Apply Initial Effects"] Startup --> Subscribe["Subscribe subsystem events"] Subscribe --> Tick["OnEnable registers scheduler"] Tick --> Runtime["Abilities, effects, and input tick while enabled"] ``` Initialization is lazy-safe: accessing `RuntimeTags`, `RuntimeAttributes`, `RuntimeEffects`, `RuntimeAbilities`, or `AbilityInputQueue` calls `EnsureInitialized()` if needed. `OnEnable` subscribes events and registers the ASC with the scheduler. `OnDisable` and disposal paths clean up active ability/effect state. ## Configuration Checklist * `Initial Attributes`: include every attribute set the actor needs before any effect applies. * `Initial Effects`: use for passives such as spawn shields, default buffs, or status tags. * `Initial Inputs`: use logical input IDs, not keyboard keys. Keyboard/gamepad mapping belongs to an input source. * Attribute hooks: attach components implementing `IAttributeChangeHook` to the same GameObject before initialization, or call `RefreshAttributeChangeHooks()` after adding hooks dynamically. * Runtime UI: bind UI components to this ASC, or let scene scripts resolve it from the actor. ## Practical Usage Patterns Grant an ability from code: ```csharp var handle = asc.RuntimeAbilities.AddAbility(abilityDefinition, level: 1); ``` Apply an effect to the actor itself: ```csharp var request = EffectApplicationRequest.CreateResolved( target: asc.gameObject, targetASC: asc, instigator: asc.gameObject, instigatorASC: asc); asc.RuntimeEffects.Apply(effectDefinition, request, level: 1); ``` Read an attribute: ```csharp if (asc.RuntimeAttributes.GetAttributeCurrentValue(healthId, out float health)) { // Update HUD. } ``` ## Debugging Checklist * If attributes are missing, confirm the actor's `Initial Attributes` contains an `AttributeSet` that includes the expected `AttributeSetDefinition`. * If initial effects do nothing, confirm the effect has modifiers or an `EffectCalculation`. * If an ability does not activate, inspect the ASC `Events` tab for `AbilityFailureReason`. * If input does not reach abilities, inspect the ASC `Inputs` tab and confirm the input source is bound. * If runtime UI does not update, confirm it references the same ASC instance and subscribes after the ASC initializes. ## Common Mistakes | Mistake | Result | Fix | | ------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------- | | Applying an effect to a GameObject without an ASC | Application fails or has no target state | Resolve the target ASC before applying. | | Treating `AbilityDefinition` as runtime state | Shared asset data is mutated accidentally | Store runtime state on `AbilityRuntime` or `AbilitySpec`. | | Adding hooks after initialization without refresh | Hook does not run | Call `RefreshAttributeChangeHooks()`. | | Binding physical keys directly to abilities | Input is hard to remap | Use `AbilityInputId` and an input source. | ## Extension Points * Add actor-specific attribute side effects with `IAttributeChangeHook`. * Add custom ability behavior by subclassing `AbilityDefinition` and `AbilityRuntime`. * Add custom effect behavior by subclassing `EffectDefinition` and `EffectRuntime`. * Add custom input by implementing `IAbilityInputSource` or `IAbilityInputContextSource`. * Add custom runtime UI by subscribing to ASC aggregate events. ## Examples and Tests * Basic Tutorial: inspect the player actor and enemy actor ASCs. * Arena Demo: inspect the player ASC during combat to see active effects, inputs, and abilities. * Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/AbilitySystemLifecycleTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/AscConvenienceApiTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/PlayMode/CorePlayModeLifecycleTests.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/ability-system-component.md?ask= ``` 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.