142 lines
4.0 KiB
Markdown
142 lines
4.0 KiB
Markdown
# 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
|