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

# Arena Demo

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

Arena is a top-down wave-survival ARPG slice built with Gameplay Ability Toolkit. You control one hero with melee combos, heavy attack, dodge, firebolt, meteor, flamethrower, warcry, resource pickups, regeneration, enemies, waves, and a final boss.

Every hit, buff, cooldown, status, cue, and resource change runs through the toolkit. The scene is meant to be played, inspected, and used as a reference implementation.

Use this demo when you are deciding whether the toolkit has enough depth for your project. It is larger than the Basic Tutorial and intentionally shows several systems interacting under player and enemy pressure.

![Practical Arena demo map showing gameplay zones and runtime feedback.](/files/UtZYCBuZyW2oAt1yuYqb)

## Why This Demo Exists

The Arena makes toolkit features visible as gameplay:

* Abilities feel like real combat actions, not isolated inspector data.
* Effects are observable through health changes, DoTs, costs, cooldowns, buffs, and pickups.
* Tags control state such as invulnerability and combo windows.
* Cues and HUD feedback are decoupled from ability runtime code.
* Training and Arena scenes provide the manual checks for combat rules.

`Training.unity` is for low-pressure ability inspection. `Arena.unity` is for validating the same rules inside the complete combat loop.

## Quick Start

1. Open the project in Unity 6000.3.10f1 or a compatible version.
2. Open one of these scenes:

| Scene                   | Purpose                                                                 |
| ----------------------- | ----------------------------------------------------------------------- |
| `Scenes/Arena.unity`    | Full wave-survival run with enemies, waves, boss, win, and lose states. |
| `Scenes/Training.unity` | Sandbox for testing all abilities on auto-resetting dummies.            |

3. Press Play.
4. Use `Training.unity` for single-ability checks before tuning the full arena loop.

### Editor Click Path

Use the Project window:

```
GameplayAbilityToolkit/Demo/Arena/Scenes/Training.unity
GameplayAbilityToolkit/Demo/Arena/Scenes/Arena.unity
```

Open `Training.unity` first if you want to test one ability at a time. Open `Arena.unity` when you want waves, enemy AI, boss flow, victory, and defeat.

### First Ten Minutes

1. Play `Training.unity`.
2. Use every ability once.
3. Toggle the event log with Backquote.
4. Watch which actions spend Mana or Stamina.
5. Stop Play Mode.
6. Open `Abilities/GA_LightAttack.asset`, `GA_Dodge.asset`, `GA_Firebolt.asset`, `GA_Flamethrower.asset`, and `GA_Meteor.asset`.
7. Open the matching `GE_*` effects they reference.
8. Play `Arena.unity` and compare the same abilities under enemy pressure.

## Controls

| Input     | Action                                                   | What it shows                                                 |
| --------- | -------------------------------------------------------- | ------------------------------------------------------------- |
| WASD      | Move                                                     | Movement speed read from `MoveSpeed`.                         |
| Mouse     | Aim / face cursor                                        | Actor control outside the toolkit, feeding ability direction. |
| LMB       | Light attack; re-press during recovery for a 3-hit combo | Runtime state machine plus `Combo.WindowOpen`.                |
| RMB       | Heavy attack                                             | Cost, cooldown, stagger, status.                              |
| Q         | Firebolt projectile                                      | Projectile hit pipeline plus burn.                            |
| E         | Meteor                                                   | Ability task, telegraph delay, ground AoE.                    |
| F hold    | Flamethrower                                             | Held input, channel lifecycle, periodic cost, sustained cue.  |
| Space     | Dodge roll                                               | Tag-gated invulnerability frames.                             |
| R         | Warcry                                                   | Duration self-buff.                                           |
| Backquote | Toggle event log                                         | Runtime observability through `GASEventLog`.                  |

Clear all waves to win. Drop to 0 HP to lose, then use Retry.

## What This Demo Demonstrates

| In the demo you see                                                | Toolkit capability                             |
| ------------------------------------------------------------------ | ---------------------------------------------- |
| HP, Mana, Stamina, MoveSpeed, AttackSpeed                          | `AttributeSetDefinition` with clamping.        |
| Damage, ability costs, red/blue pickups                            | Instant gameplay effects.                      |
| Burn that ticks and stacks to 3                                    | Periodic stacking duration effect.             |
| Dodge invulnerability and Warcry haste                             | Duration effects granting tags or modifiers.   |
| Abilities fail when resources are missing                          | Cost commit and activation failure events.     |
| Abilities grey out while unavailable                               | Cooldown queries for runtime UI.               |
| Flamethrower stops on release or Mana drain                        | Input release and channel lifecycle.           |
| Meteor waits before impact                                         | `AbilityTask_WaitDelay` and ground targeting.  |
| Impacts spawn VFX without per-ability VFX code                     | Gameplay cues mapped by tag.                   |
| Melee can whiff                                                    | Physics-driven hitbox and real target contact. |
| Enemies and player use the same damage pipeline                    | Every combat actor has an ASC.                 |
| Event overlay streams activations, effects, stacks, tags, and cues | Runtime observability events.                  |

## Subsystem Coverage

| Subsystem  | Where to inspect                                                 | Manual page                                                                                     |
| ---------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| ASC        | Player/enemy prefabs in `Prefabs/Actors/` and `Prefabs/Enemies/` | [AbilitySystemComponent](/docs/gameplay-ability-toolkit/subsystems/ability-system-component.md) |
| Attributes | Arena attribute definitions and actor attribute sets             | [Attributes](/docs/gameplay-ability-toolkit/subsystems/attributes.md)                           |
| Tags       | Arena tag assets and ability/effect tag fields                   | [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      | Player input bindings and runtime input UI                       | [Core Input](/docs/gameplay-ability-toolkit/subsystems/input.md)                                |
| Targeting  | Meteor, melee, projectile, and training target assets            | [Targeting](/docs/gameplay-ability-toolkit/subsystems/targeting.md)                             |
| Tasks      | Channel, delay, and montage wait logic                           | [Ability Tasks and Timing](/docs/gameplay-ability-toolkit/subsystems/tasks-timing.md)           |
| Cues       | Cue library and cue prefabs                                      | [Gameplay Cues](/docs/gameplay-ability-toolkit/subsystems/gameplay-cues.md)                     |
| Montage    | Attack and dodge animation timing assets                         | [Montage](/docs/gameplay-ability-toolkit/subsystems/montage.md)                                 |
| Runtime UI | HUD, status bars, event log                                      | [Runtime UI](/docs/gameplay-ability-toolkit/subsystems/runtime-ui.md)                           |

## Editor Inspection Path

After playing once, inspect the demo in this order.

### 1. Bootstrap And Configuration

Open a scene and select:

| Hierarchy object                    | What to check                                 |
| ----------------------------------- | --------------------------------------------- |
| `ArenaDemoBootstrap`                | Scene-level GAS configuration.                |
| `GameplayCueManager`                | Cue library used by the scene.                |
| `ArenaWaveManager` in `Arena.unity` | Enemy waves, spawn flow, victory progression. |
| `Main Camera`                       | Camera rig target and follow settings.        |

These objects explain how scene-level services are connected before actor gameplay starts.

### 2. Player Actor

Open:

```
GameplayAbilityToolkit/Demo/Arena/Prefabs/Actors/Player.prefab
```

Inspect:

* `AbilitySystemComponent`: initial attributes, effects, and input bindings.
* `ArenaInitialAbilities`: abilities granted to the player.
* `ArenaKeyboardInputSource`: logical input names and keys.
* `ArenaPlayerController`: movement and aim that feed ability direction.
* `WeaponHitbox`: melee contact window.

### 3. Ability Assets

Open each `GA_*` asset and ask:

| Asset             | Inspect                                                                 |
| ----------------- | ----------------------------------------------------------------------- |
| `GA_LightAttack`  | Combo stages, timing, damage effect, hit react effect, montage list.    |
| `GA_HeavyAttack`  | Cost, cooldown, windup, damage, and hit reaction.                       |
| `GA_Dodge`        | Dash duration, dash speed, invulnerability effect, montage.             |
| `GA_Firebolt`     | Projectile prefab, impact effect, burn effect, spawn offsets.           |
| `GA_Flamethrower` | Tick interval, range, mana tick, burn, sustained cue.                   |
| `GA_Meteor`       | Cast range, radius, delay, target collector, projectile/impact effects. |
| `GA_Warcry`       | Buff effect, montage, cooldown, and activation tags.                    |

### 4. Effect Assets

Open the referenced `GE_*` assets. Focus on type, duration, period, modifiers, granted tags, cues, and stack rules.

The fastest comparisons:

* `GE_LightDamage` vs `GE_HeavyDamage`
* `GE_Burn`
* `GE_Invuln`
* `GE_Haste`
* `GE_CostMana` and `GE_CostStamina`
* `GE_HealthPotion` and `GE_ManaPotion`

### 5. Presentation And Debugging

Open:

| Asset or file                | What it shows                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `Prefabs/UI/ArenaHUD.prefab` | Polished attribute bars with delayed trails, target panel, cooldown slots, feedback text, and event log. |
| `Cues/ArenaCueLibrary.asset` | Cue tags mapped to VFX prefabs.                                                                          |
| `Scripts/ArenaDebugDraw.cs`  | Scene view overlays for hitboxes, ranges, radii, and player tags.                                        |

The presentation layer should read runtime state; it should not be the owner of gameplay rules.

## Melee Design

Melee is deliberately skill-based. Attacks have windup, active, and recovery windows. During the active window, `WeaponHitbox` polls an `OverlapBox`; if no enemy is inside, the swing misses. Hits land once per swing.

Dodge grants `State.Invulnerable` for a short window. Player and enemy hit logic check the tag before applying damage.

## Under the Hood

| System                           | Where to inspect                                                             |
| -------------------------------- | ---------------------------------------------------------------------------- |
| Ability definitions and runtimes | `Scripts/Arena*AbilityDefinition.cs`, `Abilities/GA_*`                       |
| Hit detection                    | `WeaponHitbox`, `ArenaProjectile`                                            |
| Player movement and input        | `ArenaPlayerController`, `ArenaKeyboardInputSource`, `ArenaInitialAbilities` |
| Enemy AI and death               | `ArenaEnemyAI`, `ArenaActorDeath`, `ArenaWaveManager`                        |
| HUD and feedback                 | `ArenaHudPresenter`, `ArenaParticleCue`, `ArenaResultScreen`                 |
| Montages                         | `Montages/MT_*`, `MontagePlayer`, `ArenaMontageReactions`                    |

All content is committed as ScriptableObject assets, prefabs, scenes, and source files.

## Training Scene Markers

`Training.unity` uses visible zones to isolate mechanics:

| Marker             | Use it for                                 |
| ------------------ | ------------------------------------------ |
| `MeleePad`         | Light and heavy attack range checks.       |
| `RangedLane`       | Firebolt projectile travel and impact.     |
| `AoePad`           | Meteor radius and delayed impact.          |
| `FlamethrowerLane` | Held channel width, range, and mana drain. |
| `PotionPad`        | Health and Mana pickup checks.             |

Use Training for content tuning. Use Arena for pressure testing.

## Layout

```
Demo/Arena/
  Attributes/   ASDef_Arena, AS_Arena, boss variants
  Tags/         Ability.*, State.*, Effect.*, Combo.*, Cue.*
  Effects/      Damage, burn, costs, pickups, haste, hit-react, invulnerability
  Abilities/    Light, heavy, dodge, warcry, firebolt, flamethrower, meteor
  Inputs/       ArenaInputs
  Cues/         ArenaCueLibrary
  Prefabs/      Player, training dummy, enemies, pickups, projectile, VFX, HUD
  Resources/    GASConfiguration
  Montages/     AnimationMontage assets
  Art/External/ CC0 dungeon and monster sources
  Scenes/       Arena.unity, Training.unity
  Scripts/      Arena runtime components
```

## Verification

Use `Training.unity` and `Arena.unity` to verify:

* Instant damage reduces Health.
* `WeaponHitbox` hits during the active window.
* Light attack connects in range and whiffs out of range.
* 3-hit combo chains.
* Dodge i-frames negate incoming hits.
* Warcry modifies AttackSpeed and cooldown blocks repeated use.
* Projectile applies effect on contact.
* Meteor damages only targets inside its radius.
* Passive regen and pickups restore resources.
* Flamethrower damages forward targets and stops on release.
* Enemy melee respects invulnerability.
* Actors die at 0 HP.

Add `ArenaDebugDraw` to a scene root when you need to inspect melee boxes, projectile ranges, meteor radii, enemy attack ranges, or invulnerability tags in the Scene view.

## Dependencies and Assets

* Zero paid dependencies.
* Arena runtime references `GameplayAbilityToolkit.Core`, `GameplayAbilityToolkit.UI`, `Unity.TextMeshPro`, and `UnityEngine.UI`.
* Animation uses the built-in Unity Playables driver.
* Character and animation assets are CC0 Quaternius assets.
* Scene dressing uses a committed subset of Kenney Modular Dungeon Kit under `Art/External/KenneyModularDungeonKit/`.
* VFX are self-made Shuriken particle cues.
* Third-party art sources are summarized in `../../THIRD_PARTY_NOTICES.md`.

## Scope

Arena covers the core single-player surface: attributes, effects, tags, costs, cooldowns, input press/release, channels, projectiles, ground AoE, cues, montages, HUD observation, death, waves, and manual scene verification.

It does not cover networking, prediction, save/load, inventory/equipment, or DOTS/Jobs.

## Where to Look First

* Gameplay rules: read the `*Runtime.cs` and `*AbilityDefinition.cs` files in `Scripts/`.
* Content model: open `GA_*`, `GE_*`, attribute, tag, cue, and input assets in the Inspector.
* New user path: read the [Basic Tutorial](/docs/gameplay-ability-toolkit/evaluate/tutorial.md), then [How To Add an Ability](/docs/gameplay-ability-toolkit/tutorial-details/howtoaddability.md).


---

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