first commit

api/app/data/abilities/README.md

@@ -0,0 +1,141 @@
+# 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

api/app/data/abilities/basic_attack.yaml

@@ -0,0 +1,16 @@
+# Basic Attack - Default melee attack
+# Available to all characters, no mana cost, no cooldown
+
+ability_id: "basic_attack"
+name: "Basic Attack"
+description: "A standard melee attack with your equipped weapon"
+ability_type: "attack"
+base_power: 5
+damage_type: "physical"
+scaling_stat: "strength"
+scaling_factor: 0.5
+mana_cost: 0
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied: []

api/app/data/abilities/fireball.yaml

@@ -0,0 +1,25 @@
+# Fireball - Offensive spell for Arcanist class
+# Deals fire damage and applies burning DoT
+
+ability_id: "fireball"
+name: "Fireball"
+description: "Hurl a ball of fire at your enemies, dealing damage and burning them"
+ability_type: "spell"
+base_power: 30
+damage_type: "fire"
+scaling_stat: "intelligence"
+scaling_factor: 0.5
+mana_cost: 15
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied:
+  - effect_id: "burn"
+    name: "Burning"
+    effect_type: "dot"
+    duration: 3
+    power: 5
+    stat_affected: null
+    stacks: 1
+    max_stacks: 3
+    source: "fireball"

api/app/data/abilities/heal.yaml

@@ -0,0 +1,26 @@
+# Heal - Luminary class ability
+# Restores health to target ally
+
+ability_id: "heal"
+name: "Heal"
+description: "Channel divine energy to restore an ally's health"
+ability_type: "spell"
+base_power: 25
+damage_type: "holy"
+scaling_stat: "intelligence"
+scaling_factor: 0.5
+mana_cost: 10
+cooldown: 0
+is_aoe: false
+target_count: 1
+effects_applied:
+  # Healing is represented as negative DOT (HOT)
+  - effect_id: "regeneration"
+    name: "Regeneration"
+    effect_type: "hot"
+    duration: 2
+    power: 5
+    stat_affected: null
+    stacks: 1
+    max_stacks: 3
+    source: "heal"

api/app/data/abilities/shield_bash.yaml

@@ -0,0 +1,25 @@
+# Shield Bash - Vanguard class ability
+# Deals damage and stuns the target
+
+ability_id: "shield_bash"
+name: "Shield Bash"
+description: "Bash your enemy with your shield, dealing damage and stunning them briefly"
+ability_type: "skill"
+base_power: 10
+damage_type: "physical"
+scaling_stat: "strength"
+scaling_factor: 0.5
+mana_cost: 5
+cooldown: 2
+is_aoe: false
+target_count: 1
+effects_applied:
+  - effect_id: "stun"
+    name: "Stunned"
+    effect_type: "stun"
+    duration: 1
+    power: 0
+    stat_affected: null
+    stacks: 1
+    max_stacks: 1
+    source: "shield_bash"