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

# Basic Tutorial

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

The Basic Tutorial is a self-contained learning scene under `GameplayAbilityToolkit/Tutorial/Basic/`. It uses Gameplay Ability Toolkit, Unity primitives, generated textures, keyframed `.anim` clips, legacy `UnityEngine.Input`, Unity UI, and ParticleSystem cues.

Use it as your first hands-on evaluation scene. It is intentionally small and readable; it is not a production architecture template that every project must copy.

Open:

```
GameplayAbilityToolkit/Tutorial/Basic/Scenes/BasicTutorial.unity
```

Press Play, then use the controls below to observe the full flow from input to ability, effect, tag, cue, UI, and event log.

![Practical runtime UI observability diagram showing ASC events feeding bars, lists, and logs.](/files/YRorjbp2Irk5TxHJ6PBV)

## Open It In Unity

Use one of these editor paths:

| Goal                  | Where to click                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------- |
| Open the scene        | Project window > `GameplayAbilityToolkit/Tutorial/Basic/Scenes/BasicTutorial.unity`      |
| Inspect player setup  | Hierarchy > `Player`, then Inspector                                                     |
| Inspect dummy setup   | Hierarchy > `TrainingDummy`, then Inspector                                              |
| Inspect HUD wiring    | Hierarchy > `BasicTutorialHUD`, or Project window > `Prefabs/UI/BasicTutorialHUD.prefab` |
| Inspect cues          | Project window > `Cues/BasicTutorialCueLibrary.asset`                                    |
| Inspect global config | Project window > `Resources/GASConfiguration.asset`                                      |

If Unity opens the Project window in a different folder, paste the path or asset name into the Project search box. This tutorial is intentionally small enough that every relevant asset can be inspected by hand.

## Controls

| Input           |              Key | Ability          |
| --------------- | ---------------: | ---------------- |
| `PrimaryAttack` |       Left Mouse | `GA_LightAttack` |
| `Guard`         | Right Mouse hold | `GA_Guard`       |
| `FireSkill`     |                Q | `GA_FireSkill`   |
| `Heal`          |                E | `GA_Heal`        |
| `ResetDummy`    |                R | `GA_ResetDummy`  |

## What This Scene Teaches

| What you see                                 | Toolkit concept                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------- |
| Player and dummy both have HP bars           | `AbilitySystemComponent` plus shared attribute schema.                                |
| Fire and attack reduce dummy HP              | Instant `EffectDefinition` assets modifying `Health`.                                 |
| Burn ticks and stacks up to three            | Duration effect with period, stacking, and granted tag.                               |
| Guard halves incoming damage                 | Held ability granting `State.Guarding`, then runtime chooses guarded effect variants. |
| Fire Skill consumes Mana and starts cooldown | Cost effect and cooldown effect committed by ability activation.                      |
| VFX fire without ability-specific VFX code   | Gameplay cues mapped through `BasicTutorialCueLibrary`.                               |
| Event log streams each step                  | ASC and runtime subsystem events surfaced through `GASEventLog`.                      |
| Challenges complete as you play              | Game logic observing tags, effects, and ability activation.                           |

## Subsystem Coverage

| Subsystem  | Where to inspect in this scene               | Manual page                                                                                     |
| ---------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| ASC        | Hierarchy > `Player` and `TrainingDummy`     | [AbilitySystemComponent](/docs/gameplay-ability-toolkit/subsystems/ability-system-component.md) |
| Attributes | `Attributes/ASDef_BasicTutorial.asset`       | [Attributes](/docs/gameplay-ability-toolkit/subsystems/attributes.md)                           |
| Tags       | `Tags/BasicTutorialTags.asset`               | [Gameplay Tags](/docs/gameplay-ability-toolkit/subsystems/tags.md)                              |
| Abilities  | `Abilities/GA_*`                             | [Abilities](/docs/gameplay-ability-toolkit/subsystems/abilities.md)                             |
| Effects    | `Effects/GE_*`                               | [Effects](/docs/gameplay-ability-toolkit/subsystems/effects.md)                                 |
| Input      | `Inputs/BasicTutorialInputs.asset`           | [Core Input](/docs/gameplay-ability-toolkit/subsystems/input.md)                                |
| Targeting  | Fire skill targeting assets and player setup | [Targeting](/docs/gameplay-ability-toolkit/subsystems/targeting.md)                             |
| Cues       | `Cues/BasicTutorialCueLibrary.asset`         | [Gameplay Cues](/docs/gameplay-ability-toolkit/subsystems/gameplay-cues.md)                     |
| UI         | `Prefabs/UI/BasicTutorialHUD.prefab`         | [Runtime UI](/docs/gameplay-ability-toolkit/subsystems/runtime-ui.md)                           |

## Read The Scene In Four Passes

The scene is easier to understand if you inspect it in this order.

| Pass               | Goal                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------- |
| Actor ownership    | Confirm where gameplay state lives.                                                   |
| Data assets        | See the authoring data that defines attributes, tags, inputs, effects, and abilities. |
| Runtime feedback   | Watch how UI and logs observe ASC events.                                             |
| Targeting and cues | See how targets are selected and feedback is decoupled from ability code.             |

### Pass 1: Actor Ownership

Select `Player` and `TrainingDummy`. Both actors use an `AbilitySystemComponent`, so they share the same gameplay pipeline even though only the player receives input.

Check:

* The ASC has initial attributes assigned.
* The player has tutorial setup and keyboard input components.
* The dummy has actor state, hit reaction, nameplate, and burn/death visuals.

### Pass 2: Data Assets

Open the assets under `Attributes/`, `Tags/`, `Inputs/`, `Effects/`, and `Abilities/`.

Read them in this sequence:

1. `ASDef_BasicTutorial.asset`
2. `BasicTutorialTags.asset`
3. `BasicTutorialInputs.asset`
4. Cost and damage effects in `Effects/`
5. Ability assets in `Abilities/`

This mirrors the runtime dependency chain: attributes and tags exist first, then effects write attributes or grant tags, then abilities apply effects.

### Pass 3: Runtime Feedback

Open `Prefabs/UI/BasicTutorialHUD.prefab`.

Look for:

* `BasicTutorialHudPresenter`: reads player/dummy ASC state and renders bars, cooldown, burn stacks, and failures.
* `BasicTutorialChallengeTracker`: observes gameplay state and completes the guided tasks.
* Event log panel: displays ability, effect, tag, stack, and cue events.

### Pass 4: Targeting And Cues

Open the targeting prefabs and cue library:

| Asset                                         | What it proves                           |
| --------------------------------------------- | ---------------------------------------- |
| `Prefabs/Targeting/TC_LightAttack_Box.prefab` | Light attack uses a box trace.           |
| `Prefabs/Targeting/TC_FireSkill_Cone.prefab`  | Fire Skill uses a cone trace.            |
| `Cues/BasicTutorialCueLibrary.asset`          | Cue tags map to ParticleSystem feedback. |

This is the point where the scene stops being a black box: targeting chooses who receives effects, and cue tags choose feedback without ability-specific VFX code.

## Design Philosophy

The scene is tuned for legibility instead of feature breadth.

* The dummy has a world-space nameplate showing HP, burn stacks, and a Guarding badge.
* The HUD shows Health, Mana, Stamina, cooldowns, keys, challenges, and an event log.
* An auto-damage source periodically hits the player so Guard mitigation can be observed.
* The challenge tracker turns isolated inputs into a guided loop.

Guard mitigation intentionally uses tags and guarded effect variants instead of attribute math. That keeps the rule easy to inspect: Guard grants `State.Guarding`; damage code applies a smaller effect when the target has that tag.

## Folder Layout

Important paths under `GameplayAbilityToolkit/Tutorial/Basic/`:

| Folder        | Key assets                                                                     |
| ------------- | ------------------------------------------------------------------------------ |
| `Scenes/`     | `BasicTutorial.unity`                                                          |
| `Scripts/`    | Runtime tutorial components and `GameplayAbilityToolkit.Tutorial.Basic.asmdef` |
| `Attributes/` | `ASDef_BasicTutorial.asset`, `AS_BasicTutorial.asset`                          |
| `Tags/`       | `BasicTutorialTags.asset`                                                      |
| `Inputs/`     | `BasicTutorialInputs.asset`                                                    |
| `Effects/`    | `GE_LightAttackDamage`, guarded variants, burn, heal, costs, guard mitigation  |
| `Abilities/`  | `GA_LightAttack`, `GA_Guard`, `GA_FireSkill`, `GA_Heal`, `GA_ResetDummy`       |
| `Cues/`       | `BasicTutorialCueLibrary.asset`                                                |
| `Resources/`  | `GASConfiguration.asset`                                                       |
| `Prefabs/`    | Player, TrainingDummy, HUD, targeting collectors                               |

Open the assets in the Inspector as you read; this scene is meant to be inspected.

## Inspector Tour

Use this table when you are following along in the Unity editor.

| Select               | Inspector fields to check                                                                                | Why it matters                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `Player`             | `AbilitySystemComponent`, `BasicTutorialSetup`, `BasicTutorialKeyboardInputSource`, `BasicTutorialActor` | Shows actor state, granted abilities, and logical input source.    |
| `TrainingDummy`      | `AbilitySystemComponent`, `BasicTutorialActor`, `BasicTutorialDummyHitReact`                             | Shows the target actor receiving effects and playing hit feedback. |
| `AutoDamageSource`   | Source, target, guarded and unguarded damage effects, interval                                           | Makes Guard mitigation observable without enemy AI.                |
| `GameplayCueManager` | Cue library/configuration references                                                                     | Routes `Cue.*` tags to cue prefabs.                                |
| `BasicTutorialHUD`   | Player, dummy, fire ability, burn effect, UI references                                                  | Shows how UI reads ASC state without owning gameplay rules.        |

Do not edit runtime values while in Play Mode unless you are deliberately experimenting. Make persistent changes on assets or prefabs outside Play Mode.

## Attributes

`ASDef_BasicTutorial.asset` defines:

| Attribute | Base | Clamp    |
| --------- | ---: | -------- |
| `Health`  |  100 | 0 to 100 |
| `Mana`    |   80 | 0 to 80  |
| `Stamina` |  100 | 0 to 100 |

The player and dummy share the same schema through `AS_BasicTutorial.asset`.

## Tags and Inputs

`BasicTutorialTags.asset` includes:

```
Ability.Attack.Light
Ability.Defense.Guard
Ability.Skill.Fire
State.Attacking
State.Guarding
State.Dead
Effect.Burn
Cue.Hit
Cue.Block
Cue.Fire
Cue.Fire.Charge
Cue.Fire.Impact
Cue.Burn
Cue.Heal
```

`BasicTutorialInputs.asset` includes:

```
PrimaryAttack
Guard
FireSkill
Heal
ResetDummy
```

`BasicTutorialKeyboardInputSource` raises logical toolkit input events from `UnityEngine.Input`. The player's `AbilitySystemComponent` has an initial binding set mapping those logical inputs to the tutorial abilities.

## Effects

| Effect                         | Type     | Important values                                                            |
| ------------------------------ | -------- | --------------------------------------------------------------------------- |
| `GE_LightAttackDamage`         | Instant  | `Health Add -18`, cue `Cue.Hit`                                             |
| `GE_LightAttackDamage_Guarded` | Instant  | `Health Add -9`, cue `Cue.Hit`                                              |
| `GE_FireImpactDamage`          | Instant  | `Health Add -22`, cue `Cue.Fire`                                            |
| `GE_FireImpactDamage_Guarded`  | Instant  | `Health Add -11`, cue `Cue.Fire`                                            |
| `GE_BurnDoT`                   | Duration | Duration `5`, period `1`, max stack `3`, `Health Add -4`, tag `Effect.Burn` |
| `GE_BurnDoT_Guarded`           | Duration | Duration `5`, period `1`, max stack `3`, `Health Add -2`, tag `Effect.Burn` |
| `GE_Heal`                      | Instant  | `Health Add 28`, cue `Cue.Heal`                                             |
| `GE_StaminaCost`               | Instant  | `Stamina Add -12`                                                           |
| `GE_ManaCost`                  | Instant  | `Mana Add -24`                                                              |
| `GE_GuardMitigation`           | Infinite | Grants `State.Guarding`, cue `Cue.Block`                                    |

Costs are ordinary cost effects on ability definitions. This is the same pattern you use in your own content.

## Abilities

| Ability          | What it does                                                                                                                                                    |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GA_LightAttack` | Plays `Player_LightAttack.anim`, consumes stamina, grants `State.Attacking`, resolves `TC_LightAttack_Box` at `0.24` seconds, applies normal or guarded damage. |
| `GA_Guard`       | Plays guard enter animation, stays active while Right Mouse is held, applies `GE_GuardMitigation`, removes it on release.                                       |
| `GA_FireSkill`   | Plays `Player_FireCast.anim`, consumes mana, starts a 3 second cooldown, resolves `TC_FireSkill_Cone` at `0.42` seconds, applies impact and burn effects.       |
| `GA_Heal`        | Plays `Player_Heal.anim`, consumes mana, starts a 1 second cooldown, applies `GE_Heal` to the player.                                                           |
| `GA_ResetDummy`  | Restores dummy state, removes burn and `State.Dead`, cleans up cues, plays respawn animation.                                                                   |

The matching montage assets live beside the animation clips for inspection.

## Targeting, Cues, and UI

Melee targeting uses `Prefabs/Targeting/TC_LightAttack_Box.prefab` with a box trace. Fire targeting uses `Prefabs/Targeting/TC_FireSkill_Cone.prefab` with a cone trace.

Cue mappings live in `Cues/BasicTutorialCueLibrary.asset` and are referenced by `Resources/GASConfiguration.asset`. The scene has a `GameplayCueManager`.

The HUD has five visible surfaces:

1. Player Health, Mana, Stamina, and cooldowns.
2. Static key cheatsheet.
3. Challenge panel.
4. `GAS Event Log`.
5. Summary overlay after all challenges complete.

## Runtime Flow

```mermaid
flowchart LR
    Input["Input"]
    Ability["Ability activates"]
    Cost["Cost/cooldown committed"]
    Target["Targets collected"]
    Effect["Effects applied"]
    Tags["Tags and stacks update"]
    Cues["Cues and HUD update"]

    Input --> Ability --> Cost --> Target --> Effect --> Tags --> Cues
```

## Guided Playthrough

Use this playthrough when validating the tutorial after changing assets:

1. Press Play and confirm the HUD appears immediately.
2. Left-click once. The dummy should take direct damage and the event log should show activation and effect application.
3. Press Q repeatedly after cooldowns. The dummy should show burn stacks and periodic HP loss.
4. Hold Right Mouse for at least two seconds. The Guard challenge should complete and incoming auto-damage should be reduced.
5. Press E after taking damage. The player Health bar should increase and Mana should decrease.
6. Press R. The dummy should reset Health, burn stacks, dead state, and cue visuals.
7. Complete all challenges and confirm the summary overlay appears.

If any step fails, inspect the asset that owns that rule before editing code.

## Verification Checklist

* [ ] Dummy nameplate shows current HP.
* [ ] Burn stack chip appears and reaches 3 after repeated Fire Skill hits.
* [ ] Cheatsheet is visible from frame one.
* [ ] Challenge panel starts with three unchecked entries.
* [ ] Event log streams one colored line per major runtime event.
* [ ] Pressing Q shows charge feedback, impact feedback, mana cost, fire damage, burn, and cue entries.
* [ ] Holding Right Mouse adds `State.Guarding`; the next auto-damage tick uses the guarded damage variant.
* [ ] Pressing E heals the player and triggers `Cue.Heal`.
* [ ] Pressing R resets the dummy, removes burn, and cleans up cues.
* [ ] Completing all three challenges shows the summary overlay.

## Troubleshooting

| Problem                   | Check                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Missing UniTask           | UniTask package is resolved and `GAS_HAS_UNITASK` is set.                                                  |
| Missing config            | `Resources/GASConfiguration.asset` references tags, inputs, and cue library.                               |
| Invalid tags              | Open `Tools > Gameplay Ability Toolkit > Dashboard > Tags` and validate.                                   |
| Null cue library          | Assign `BasicTutorialCueLibrary.asset` in configuration.                                                   |
| Attacks miss unexpectedly | Target dummy root is on `Default`; player root should not be targetable.                                   |
| No attributes             | Player and dummy prefabs have `AbilitySystemComponent` and `AS_BasicTutorial.asset` in Initial Attributes. |

## Next Steps

* Follow [How To Add an Ability](/docs/gameplay-ability-toolkit/tutorial-details/howtoaddability.md) to create a new ability.
* Read [Advanced Topics](/docs/gameplay-ability-toolkit/tutorial-details/advancedtopics.md) for ability tasks, overflow, targeting indicators, inhibition, hooks, and custom calculators.
* Read the [Arena Demo](/docs/gameplay-ability-toolkit/try-it/arena.md) for a complete combat slice.


---

# 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/basictutorial.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.