# Abilities

Abilities are the core of the Combat plugin. An ability is any action a character performs: attacking, casting a spell, drinking a potion, buffing an ally, or placing an area effect.

## Creating an Ability

Open the Spark Editor, go to **Combat > Abilities** and click **Create New**.

Each ability entry defines:

| Field           | Description                                               |
| --------------- | --------------------------------------------------------- |
| Display Name    | Name shown in-game.                                       |
| Description     | Tooltip text.                                             |
| Icon            | Sprite for UI display.                                    |
| Ability Type    | Determines targeting behavior and area of effect.         |
| Activation Type | Determines cast timing (instant, channeled, incantation). |
| Effects         | List of effects that execute when the ability hits.       |

## Ability Types

The ability type controls targeting and area of effect:

| Type                         | Description                                                      |
| ---------------------------- | ---------------------------------------------------------------- |
| **Direct Target**            | Targets a single entity. Requires line of sight and range check. |
| **Action Target**            | Targets the entity in front of the caster (action game style).   |
| **Self**                     | Targets the caster. No targeting needed.                         |
| **AoE (Area of Effect)**     | Affects all entities within a radius around a point.             |
| **Direct Target AoE**        | Targets an entity, then applies effects in a radius around them. |
| **Direct Target Projectile** | Fires a projectile at a target.                                  |
| **Action Projectile**        | Fires a projectile in the forward direction.                     |
| **Ground**                   | Targets a point on the ground (click-to-place).                  |
| **Cone**                     | Affects entities in a cone in front of the caster.               |
| **Rectangle**                | Affects entities in a rectangular area.                          |
| **Aura**                     | Continuously applies effects to nearby entities.                 |

Choose the type that matches your ability. A sword slash might use Action Target or Cone. A fireball might use Direct Target Projectile. A heal might use Self or Direct Target.

## Activation Types

The activation type controls how the ability is cast:

| Type            | Description                                                                               |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Instant**     | Fires immediately with no cast time.                                                      |
| **Channel**     | The caster channels for a fixed duration. Uses an animator bool for animation.            |
| **Incantation** | The caster performs a cast animation. Fires when animation completes. Can be interrupted. |

## Effects

Effects are the actions an ability performs when it hits. Each ability has a list of effects that execute in order. Every effect has an optional **Delay** field (0–10 seconds) that delays its execution after the ability fires.

Spark includes **8 built-in effect types**:

### Damage Effect

Deals damage to an entity by reducing a target stat. This is the primary combat effect.

| Field                      | Description                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------ |
| Base Damage                | Base damage amount before formulas and scaling.                                      |
| Main Damage Type           | Primary damage classification (e.g., Physical, Magical).                             |
| Secondary Damage Type      | Optional sub-classification (e.g., Fire, Frost) for more precise scaling.            |
| Calculation Formula        | Optional nCalc formula for custom damage calculation.                                |
| Target Stat                | The stat to reduce (e.g., Health).                                                   |
| Status Condition Modifiers | Bonus damage based on active statuses on the target (flat or percentage, per-stack). |
| Play Hit Animation         | Trigger the "Hit" animator parameter on the target.                                  |
| Play VFX                   | Spawn a visual effect on the target with configurable offset, scale, and duration.   |
| Stagger NPC                | Stop NPC movement on hit for a configurable duration.                                |
| Play Audio                 | Play a sound effect on hit.                                                          |

### Healing Effect

Restores a target stat on an entity. Works identically to Damage but adds instead of subtracts.

| Field                      | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| Base Healing               | Base healing amount before formulas and scaling.       |
| Main Healing Type          | Primary healing classification (e.g., Direct Heal).    |
| Secondary Healing Type     | Optional sub-classification (e.g., Holy, Nature).      |
| Calculation Formula        | Optional nCalc formula for custom healing calculation. |
| Target Stat                | The stat to increase (e.g., Health).                   |
| Status Condition Modifiers | Bonus healing based on active statuses on the target.  |
| Play Audio                 | Play a sound effect on heal.                           |

### Apply Status Effect

Applies a status effect to the target entity.

| Field             | Description                                               |
| ----------------- | --------------------------------------------------------- |
| Status Entry      | The status to apply.                                      |
| Duration Override | Override the status's default duration (0 = use default). |
| Play Audio        | Play a sound effect on application.                       |

### Modify Stat Effect

Temporarily modifies stat values while a status is active. When the status ends, modifications are automatically reversed.

| Field               | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| Stat Modifications  | List of modifications, each with:                                |
| — Target Stat       | Which stat to modify.                                            |
| — Target Property   | Which property (e.g., "value", "current", "maximum").            |
| — Modification Type | **Add**, **Subtract**, **Multiply**, **Percentage**, or **Set**. |
| — Value             | The amount for the chosen modification type.                     |

### Knockback Effect

Pushes the target away from the caster. Requires a **KnockbackReceiver** component on the target.

| Field        | Description                                                       |
| ------------ | ----------------------------------------------------------------- |
| Distance     | Distance in meters the target is pushed.                          |
| Duration     | How long the knockback movement takes (0.05–2 seconds).           |
| Curve        | Animation curve controlling knockback speed over time.            |
| Always Apply | Bypass ability restrictions and apply regardless of target state. |
| Play Audio   | Play a sound effect on knockback.                                 |

### Damage Object Effect

Deals damage to **ObjectCombatEntity** targets (destructible objects in the world, separate from normal entity damage).

| Field         | Description                          |
| ------------- | ------------------------------------ |
| Object Damage | Damage amount to deal to the object. |

### Dispel Effect

Removes dispellable status effects from the target.

| Field        | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| Dispel Count | Number of statuses to remove (0 = remove all dispellable).           |
| Target Tag   | Only dispel statuses with this tag (empty = any dispellable status). |

### Trigger Effect

Executes a Spark trigger sequence as an ability effect. This bridges the ability system with the trigger system, letting you use any trigger type (give items, load scenes, gain currency, etc.) as part of an ability.

| Field              | Description                   |
| ------------------ | ----------------------------- |
| Trigger To Execute | The trigger entry to execute. |

## Combos

Combos are sequences of abilities that chain together. Create combo entries in the **Combat > Abilities > Combos** tab. A combo defines an ordered list of abilities that must be activated in sequence within a time window.

## Tooltip Keywords

Tooltip keywords are special terms that appear highlighted in ability descriptions. For example, "Burning" could be a keyword that shows its own tooltip when hovered.

Create keywords in the **Combat > Abilities > Tooltip Keywords** tab. Each keyword has a display name, description, and color.


---

# Agent Instructions: 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://docs.sparkframework.dev/documentation/user-guide/plugins/combat/abilities.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.