> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/DarkoniusXNG/Legends-of-Dota-Redux/llms.txt
> Use this file to discover all available pages before exploring further.

# NPC Ability Definition Files

> How abilities are defined in npc_abilities_custom.txt and npc_abilities_override.txt.

Dota 2 defines abilities in KV files that follow the `DOTAAbilities` schema. Legends of Dota Redux uses two files to extend and override the base game's ability data:

| File                         | Purpose                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `npc_abilities_custom.txt`   | Defines brand-new abilities that do not exist in the base game.                                    |
| `npc_abilities_override.txt` | Overrides specific fields on existing Dota 2 abilities (e.g. adjusted cooldowns or changed flags). |

Both files live at `scripts/npc/` inside the addon directory.

***

## npc\_abilities\_custom.txt

This file does **not** contain ability blocks directly. Instead, it is entirely composed of `#base` directives that include individual ability files:

```
#base "abilities\aa\angel_arena_archmage_anomaly.txt"
#base "abilities\aa\angel_arena_berserk.txt"
#base "abilities\overflow\spectral_form.txt"
#base "abilities\custom\ranged_punch.txt"
#base "abilities\custom\basic_mana_bonus.txt"
...
```

Each `#base`-included file contains one or more ability definitions under the root `DOTAAbilities` block. This structure keeps individual abilities self-contained and easy to locate.

## npc\_abilities\_override.txt

Similarly, `npc_abilities_override.txt` uses `#base` directives to include per-hero override files:

```
#base "heroes\abaddon.txt"
#base "heroes\alchemist.txt"
#base "heroes\arc_warden.txt"
...
```

Each hero override file patches specific fields on existing Dota 2 abilities without redefining the whole block.

***

## KV Ability Block Format

Every ability block lives inside a `DOTAAbilities` root key:

```
"DOTAAbilities"
{
    "ability_name"
    {
        "BaseClass"            "<class>"
        "ScriptFile"           "<path to lua file>"  // Lua abilities only
        "AbilityTextureName"   "<icon name>"
        "AbilityBehavior"      "<behavior flags>"
        "AbilityCastRange"     "<per-level values>"
        "AbilityManaCost"      "<per-level values>"
        "AbilityCooldown"      "<per-level values>"
        "AbilityCastPoint"     "<seconds>"

        "AbilityValues"
        {
            "my_special_value"  "100 200 300 400"
        }
    }
}
```

### Common Fields

| Field                | Description                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `BaseClass`          | The C++ base class. Use `ability_lua` for Lua-implemented abilities or a specific Dota base class (e.g. `ability_datadriven`). |
| `ScriptFile`         | Path to the Lua script relative to `scripts/vscripts/`. Required when `BaseClass` is `ability_lua`.                            |
| `AbilityTextureName` | The icon to display, using the internal ability name of any Dota 2 or custom ability.                                          |
| `AbilityBehavior`    | Pipe-separated behaviour flags (see table below).                                                                              |
| `AbilityCastRange`   | Cast range in units, one value per level separated by spaces.                                                                  |
| `AbilityManaCost`    | Mana cost, one value per level.                                                                                                |
| `AbilityCooldown`    | Cooldown in seconds, one value per level.                                                                                      |
| `AbilityCastPoint`   | Cast animation time in seconds.                                                                                                |
| `AbilityValues`      | Sub-block of named special values accessible from Lua via `ability:GetSpecialValueFor()`.                                      |

### AbilityBehavior Flags

| Flag                                | Meaning                                        |
| ----------------------------------- | ---------------------------------------------- |
| `DOTA_ABILITY_BEHAVIOR_NO_TARGET`   | No target required; fires immediately on cast. |
| `DOTA_ABILITY_BEHAVIOR_UNIT_TARGET` | Targets a single unit.                         |
| `DOTA_ABILITY_BEHAVIOR_POINT`       | Targets a ground location.                     |
| `DOTA_ABILITY_BEHAVIOR_AOE`         | Area of effect; shows a radius ring on cast.   |
| `DOTA_ABILITY_BEHAVIOR_PASSIVE`     | Passive ability — no cast button.              |
| `DOTA_ABILITY_BEHAVIOR_TOGGLE`      | Toggleable on/off.                             |
| `DOTA_ABILITY_BEHAVIOR_CHANNELLED`  | Channelled; interrupted by movement or stuns.  |
| `DOTA_ABILITY_BEHAVIOR_AUTOCAST`    | Can be set to auto-cast.                       |

Multiple flags are combined with a space-separated list:

```
"AbilityBehavior"  "DOTA_ABILITY_BEHAVIOR_UNIT_TARGET | DOTA_ABILITY_BEHAVIOR_AOE"
```

***

## Real Example: ranged\_punch

The following is the full definition for `ranged_punch`, a custom Lua ability:

```
"DOTAAbilities"
{
    "ranged_punch"
    {
        "BaseClass"          "ability_lua"
        "ScriptFile"         "abilities/ranged_punch.lua"
        "AbilityTextureName" "tusk_walrus_punch"
        "AbilityBehavior"    "DOTA_ABILITY_BEHAVIOR_POINT"
        "AbilityCastRange"   "1000 1200 1400 1600"
        "AbilityManaCost"    "90"
        "AbilityCooldown"    "13 12 11 10"
        "AbilityCastPoint"   "0.05"

        "AbilityValues"
        {
            "projectile_speed"  "1000 1200 1400 1600"
            "punch_damage"      "50 100 150 200"
            "radius"
            {
                "value"                  "150"
                "affected_by_aoe_increase" "1"
            }
            "knockback_distance"
            {
                "value"                  "350"
                "affected_by_aoe_increase" "1"
            }
        }
    }
}
```

### How the Lua file links

The `ScriptFile` path points to a Lua file at `scripts/vscripts/abilities/ranged_punch.lua`. That file defines a class that extends `BaseAbility` (or a Redux base class) and implements the ability logic:

```lua theme={null}
ranged_punch = class({})

function ranged_punch:OnSpellStart()
    local caster = self:GetCaster()
    local point  = self:GetCursorPosition()
    local damage = self:GetSpecialValueFor("punch_damage")
    -- ...
end
```

The KV `AbilityValues` sub-block is what `GetSpecialValueFor("punch_damage")` reads. Scepter/Shard upgrades, talent bonuses, and AoE increase flags are all handled through this values block.

***

## Adding a New Custom Ability

1. Create a new `.txt` file under `scripts/npc/abilities/custom/my_ability.txt` with the `DOTAAbilities` block.
2. Add a `#base` line to `npc_abilities_custom.txt`:
   ```
   #base "abilities\custom\my_ability.txt"
   ```
3. Create the corresponding Lua script at `scripts/vscripts/abilities/my_ability.lua`.
4. Add the ability name to `abilities.kv` in the appropriate bracket.
5. Restart the server to pick up the new files.