Code_of_Conquest/api/app/data/abilities/README.md

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:

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:

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:

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