> 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/try-it/01-getting-started.md).

# Getting Started

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/start/01-getting-started?fallback=true>

This page takes you from a fresh import to an actor whose `Health` attribute drops when an instant damage effect is applied.

You will create the required project assets, attach an `AbilitySystemComponent`, define two attributes, and apply your first `EffectDefinition`.

Use this page as a first adoption check. When you finish it, you will know whether the package imports cleanly, whether the Dashboard workflow fits your project, and whether the core actor/attribute/effect loop feels right before you inspect larger samples.

## What This Proves

| You verify                                   | Why it matters                                                                                 |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Dashboard setup works                        | The project has the required configuration, tag, cue, and input libraries.                     |
| `AbilitySystemComponent` can own actor state | Actors can carry attributes, effects, abilities, tags, and input bindings in one place.        |
| Attributes and effects connect               | A data-authored `EffectDefinition` can change runtime `Health` without hard-coded scene logic. |
| Play Mode feedback is visible                | You can confirm behavior through Console logs, HUD/debug tools, or tests before scaling up.    |

## Prerequisites

* Unity 2022.3 LTS or newer.
* [Cysharp UniTask](https://github.com/Cysharp/UniTask) 2.5+ in `Packages/manifest.json`.

> **Dependency note:** UniTask is a required runtime dependency. If it is missing, the dependency bootstrap assembly still compiles and prompts you to install it from `Tools > Gameplay Ability Toolkit > Dashboard > Dependencies`.

## Step 1: Import the Toolkit

Copy `GameplayAbilityToolkit/` anywhere under `Assets/`. A common layout is:

```
Assets/
  Plugins/
    GameplayAbilityToolkit/
```

Unity recompiles after import. If UniTask is not installed yet, only the bootstrap editor assembly is enabled until the dependency is resolved.

## Step 2: Create the Project Assets

Open `Tools > Gameplay Ability Toolkit > Dashboard`, then select **Setup**. The page shows which required assets are missing.

![Unity Editor screenshot of the dashboard Setup page after project assets are configured.](/files/DhEqLyp4g8f3INfnUM9i)

Click **Quick Setup** and choose a target folder. The default is `Assets/Settings/GAS/`.

Quick Setup creates and wires these assets:

| Asset                       | Purpose                                                           |
| --------------------------- | ----------------------------------------------------------------- |
| `GASConfiguration.asset`    | Global runtime configuration.                                     |
| `GameplayTagAsset.asset`    | Tag registry used by drawers, validation, and runtime tag lookup. |
| `GameplayCueLibrary.asset`  | Cue tag to notify-cue mapping.                                    |
| `AbilityInputLibrary.asset` | Logical input names used by ability bindings.                     |

When the setup page is green, the project-level configuration is ready.

### Editor Click Path

1. In the top menu, click `Tools`.
2. Click `Gameplay Ability Toolkit`.
3. Click `Dashboard`.
4. In the left navigation, click **Setup**.
5. If the status strip says **NEEDS SETUP**, click **Quick Setup**.
6. Choose a folder under `Assets/`.
7. Click **Validate** after setup completes.

If your project is already configured, the dashboard shows **READY**. Use **Select Config** to inspect the active `GASConfiguration.asset`.

### What To Check On The Setup Page

| Area            | What to verify                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| Status strip    | `READY` means required core assets are assigned.                                                      |
| Project Board   | Configuration, tag asset, cue library, input library, target inputs, cue pool, and logging are valid. |
| Ability cards   | Shortcuts to Authoring, Abilities, Effects, Input, Cues, Tags, Logging, and Extensions.               |
| Asset Workbench | Quick creation buttons for common toolkit assets.                                                     |

In a fresh project, **Quick Setup** usually creates assets under `Assets/Settings/GAS/`. In this repository, sample scenes can already provide their own configuration assets, so the screenshot may show an existing demo configuration as ready.

## Step 3: Create an Actor

In any scene:

1. Create an empty GameObject named `Actor`.
2. Add `AbilitySystemComponent` with `Component > Gameplay Ability Toolkit > Ability System Component`.
3. Inspect the component. Attribute, effect, ability, and input lists are empty until you grant assets.

The `AbilitySystemComponent` is the runtime owner for an actor. Most gameplay state flows through its subsystems.

### Editor Click Path

1. In the Hierarchy, right-click and choose `Create Empty`.
2. Rename the GameObject to `Actor`.
3. Select `Actor`.
4. In the Inspector, click **Add Component**.
5. Search for `Ability System Component`.
6. Add the component.

After adding the component, keep the Inspector open. The lists are empty until you add attributes, effects, abilities, and input bindings.

## Step 4: Define Attributes

Create a simple Health/Mana schema:

1. In the Project view, right-click and choose `Create > Gameplay Ability Toolkit > Attribute Set Definition`.
2. Name the asset `ASDef_Vitals`.
3. Add two attributes:

| Attribute | Min | Max |
| --------- | --: | --: |
| `Health`  |   0 | 100 |
| `Mana`    |   0 | 100 |

Create the per-actor value asset:

1. Right-click again and choose `Create > Gameplay Ability Toolkit > Attribute Set`.
2. Name it `AS_Vitals`.
3. Assign `ASDef_Vitals` to its `Definition`.
4. Set initial values.
5. Drop `AS_Vitals` into the actor's `Initial Attributes` list.

### Editor Click Path

1. In the Project window, navigate to your gameplay asset folder.
2. Right-click the folder.
3. Choose `Create > Gameplay Ability Toolkit > Attribute Set Definition`.
4. Name it `ASDef_Vitals`.
5. Select the new asset and add `Health` and `Mana` in the Inspector.
6. Right-click again and create an `Attribute Set`.
7. Name it `AS_Vitals`.
8. Assign `ASDef_Vitals` to the set's `Definition` field.
9. Select `Actor`.
10. In `AbilitySystemComponent > Initial Attributes`, add `AS_Vitals`.

### Naming Convention

| Prefix   | Meaning                                      |
| -------- | -------------------------------------------- |
| `ASDef_` | Attribute set definition/schema.             |
| `AS_`    | Per-actor attribute values for a definition. |
| `GE_`    | Gameplay effect.                             |
| `GA_`    | Gameplay ability.                            |
| `GC_`    | Gameplay cue prefab or cue behavior.         |

## Step 5: Apply an Instant Damage Effect

Create an `EffectDefinition` named `GE_Damage`:

| Field              | Value                     |
| ------------------ | ------------------------- |
| Type               | `Instant`                 |
| Modifier operation | `Add`                     |
| Target attribute   | `Health`                  |
| Magnitude          | `LevelBased`, value `-10` |

Add a small script to the same actor:

```csharp
using GameplayAbilityToolkit.Core;
using UnityEngine;

public class HitMe : MonoBehaviour
{
    public EffectDefinition Damage;
    public AttributeSetDefinition VitalsDefinition;

    private AbilitySystemComponent _asc;
    private AttributeId _healthId;

    private void Awake()
    {
        _asc = GetComponent<AbilitySystemComponent>();
        _healthId = AttributeId.Create(VitalsDefinition, "Health");
    }

    private void Update()
    {
        if (!Input.GetKeyDown(KeyCode.Space)) return;

        var ctx = EffectApplicationRequest.Create(
            target: gameObject,
            instigator: gameObject);

        _asc.RuntimeEffects.Apply(Damage, ctx, level: 1);

        if (_asc.TryGetAttributeCurrentValue(_healthId, out float health))
        {
            Logger.Info(LogCategory.Attribute, $"Health = {health}", this);
        }
    }
}
```

Press Play, then press Space. `Health` should drop by 10 each time.

### Editor Click Path

1. Open the Project window.
2. Right-click your gameplay asset folder.
3. Choose `Create > Gameplay Ability Toolkit > Effect Asset...`.
4. Select `EffectDefinition`.
5. Click **Create**.
6. Rename the asset to `GE_Damage`.
7. In the Inspector, set `Type` to `Instant`.
8. Add one modifier targeting `Health`.
9. Set operation to `Add`.
10. Set magnitude to a level-based value of `-10`.
11. Assign `GE_Damage` to the `Damage` field on the temporary `HitMe` component.
12. Assign `ASDef_Vitals` to `VitalsDefinition`.

### Verify In Play Mode

* The Console logs a Health value every time Space is pressed.
* Health decreases by 10 per press.
* Health never goes below the configured clamp minimum.
* If nothing happens, confirm the actor has both `AbilitySystemComponent` and `AS_Vitals`.
* If the attribute lookup fails, confirm the script references the same `ASDef_Vitals` asset used by `AS_Vitals`.

## What You Just Built

```mermaid
flowchart LR
    Actor["Actor GameObject"]
    ASC["AbilitySystemComponent"]
    Attr["AS_Vitals attribute set"]
    Effect["GE_Damage instant effect"]
    Result["Health current value changes"]

    Actor --> ASC
    Attr --> ASC
    Effect --> ASC
    ASC --> Result
```

## Next Steps

* Read [Architecture](/docs/gameplay-ability-toolkit/build-with-it/02-architecture.md) to understand why definitions, specs, and runtime objects are separated.
* Read [Authoring Abilities](/docs/gameplay-ability-toolkit/build-with-it/03-authoring-abilities.md) to activate effects through reusable ability assets.
* Read [Authoring Effects](/docs/gameplay-ability-toolkit/build-with-it/04-authoring-effects.md) to build duration buffs, stacking DoTs, passives, conditional effects, and overflow effects.
* Open the [Basic Tutorial](/docs/gameplay-ability-toolkit/try-it/basictutorial.md) when you want a playable scene that shows the same flow in context.


---

# 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/try-it/01-getting-started.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.