# Ability Configuration Files

This directory contains YAML configuration files that define all abilities in the game.

## Format

Each ability is defined in a separate `.yaml` file with the following structure:

```yaml
ability_id: "unique_identifier"
name: "Display Name"
description: "What the ability does"
ability_type: "attack|spell|skill|item_use|defend"
base_power: 0                    # Base damage or healing
damage_type: "physical|fire|ice|lightning|holy|shadow|poison"
scaling_stat: "strength|dexterity|constitution|intelligence|wisdom|charisma"
scaling_factor: 0.5              # Multiplier for scaling stat
mana_cost: 0                     # MP required to use
cooldown: 0                      # Turns before can be used again
is_aoe: false                    # Whether it affects multiple targets
target_count: 1                  # Number of targets (0 = all enemies)
effects_applied: []              # List of effects to apply on hit
```

## Effect Format

Effects applied by abilities use this structure:

```yaml
effects_applied:
  - effect_id: "unique_id"
    name: "Effect Name"
    effect_type: "buff|debuff|dot|hot|stun|shield"
    duration: 3                  # Turns before expiration
    power: 5                     # Damage/healing/modifier per turn
    stat_affected: "strength"    # For buffs/debuffs only (null otherwise)
    stacks: 1                    # Initial stack count
    max_stacks: 5                # Maximum stacks allowed
    source: "ability_id"         # Which ability applied this
```

## Effect Types

| Type | Power Usage | Example |
|------|-------------|---------|
| `buff` | Stat modifier (×stacks) | +5 strength per stack |
| `debuff` | Stat modifier (×stacks) | -3 defense per stack |
| `dot` | Damage per turn (×stacks) | 5 poison damage per turn |
| `hot` | Healing per turn (×stacks) | 8 HP regeneration per turn |
| `stun` | Not used | Prevents actions for duration |
| `shield` | Shield strength (×stacks) | 50 damage absorption |

## Damage Calculation

Abilities calculate their final power using this formula:

```
Final Power = base_power + (scaling_stat × scaling_factor)
Minimum power is always 1
```

**Examples:**
- Fireball with 30 base_power, INT scaling 0.5, caster has 16 INT:
  - 30 + (16 × 0.5) = 38 power
- Shield Bash with 10 base_power, STR scaling 0.5, caster has 20 STR:
  - 10 + (20 × 0.5) = 20 power

## Loading Abilities

Abilities are loaded via the `AbilityLoader` class:

```python
from app.models.abilities import AbilityLoader

loader = AbilityLoader()
fireball = loader.load_ability("fireball")
power = fireball.calculate_power(caster_stats)
```

## Example Abilities

### basic_attack.yaml
- Simple physical attack
- No mana cost or cooldown
- Available to all characters

### fireball.yaml
- Offensive spell
- Deals fire damage + applies burning DoT
- Costs 15 MP, no cooldown

### shield_bash.yaml
- Vanguard class skill
- Deals damage + stuns for 1 turn
- Costs 5 MP, 2 turn cooldown

### heal.yaml
- Luminary class spell
- Restores health + applies regeneration HoT
- Costs 10 MP, no cooldown

## Creating New Abilities

1. Create a new `.yaml` file in this directory
2. Follow the format above
3. Set appropriate values for your ability
4. Ability will be automatically available via `AbilityLoader`
5. No code changes required!

## Guidelines

**Power Scaling:**
- Basic attacks: 5-10 base power
- Spells: 20-40 base power
- Skills: 10-25 base power
- Scaling factor typically 0.5 (50% of stat)

**Mana Costs:**
- Basic attacks: 0 MP
- Low-tier spells: 5-10 MP
- Mid-tier spells: 15-20 MP
- High-tier spells: 25-30 MP
- Ultimate abilities: 40-50 MP

**Cooldowns:**
- No cooldown (0): Most spells and basic attacks
- Short (1-2 turns): Common skills
- Medium (3-5 turns): Powerful skills
- Long (5-10 turns): Ultimate abilities

**Effect Duration:**
- Instant effects (stun): 1 turn
- Short DoT/HoT: 2-3 turns
- Long DoT/HoT: 4-5 turns
- Buffs/debuffs: 2-4 turns

**Effect Power:**
- Weak DoT: 3-5 damage per turn
- Medium DoT: 8-12 damage per turn
- Strong DoT: 15-20 damage per turn
- Stat modifiers: 3-10 points per stack