Mana-Loop/docs/skills.md

# Mana Loop - Skill System Documentation

## Overview

The skill system in Mana Loop allows players to specialize their character through a deep progression system. Skills are organized by attunement, with each attunement providing access to specific skill categories.

## Core Mechanics

### Skill Levels

- Most skills level from **1 to 10**
- Some skills cap at **level 5** (specialized skills)
- Research skills are **level 1 only** (unlock effects)

### Tier Up System

When a skill reaches max level, it can **tier up**:
- **Tier 2, Level 1 = Tier 1, Level 10** in power
- Each tier multiplies the skill's base effect by 10x
- Maximum of 5 tiers per skill
- Tiering up requires attunement level prerequisites

### Milestone Upgrades (The Perk Tree)

At **every 5 levels** (5 and 10), you choose **1 upgrade/perk** from an upgrade tree:

- Starts with 3 base choices per milestone
- Each choice leads to branching paths
- You can always choose from previously available options
- Upgrades can be **upgraded again** at future milestones
- Upgrades meaningfully impact how the skill works

#### Example: Mana Well Upgrade Tree

```
Level 5 Choices:
├── Expanded Capacity (+25% max mana)
│   └── Level 10 upgrade: Deep Reservoir (+50% max mana)
│       └── Future: Can sacrifice capacity for regen
├── Natural Spring (+0.5 regen)
│   └── Level 10 upgrade: Flowing Spring (+1 regen)
│       └── Future: Regen scales with max mana
└── Mana Threshold (+20% max mana, -10% regen)
    └── Level 10 upgrade: Mana Conversion (Convert capacity to click bonus)
        └── Future: Threshold mechanics

Level 10 Choices (additional):
├── Mana Echo (10% chance double mana from clicks)
├── Emergency Reserve (Keep 10% mana on loop reset)
└── Deep Wellspring (+50% meditation efficiency)
```

### Study System

Leveling skills requires:
1. **Mana cost** - Paid upfront to begin study
2. **Study time** - Hours required to complete
3. **Active studying** - Must be in "study" action mode

Study costs scale with:
- Current level (higher levels = more expensive)
- Skill tier (higher tiers = more expensive)
- Focused Mind skill (reduces cost)

### Attunement Requirements

Skills have attunement requirements for:
1. **Access** - Which attunement unlocks the skill category
2. **Tier Up** - Required attunement levels to advance tiers

| Requirement Type | Example |
|-----------------|---------|
| Single Attunement | Enchanting skills require Enchanter |
| Multiple Attunements | Hybrid skills require both attunements leveled |
| Any Attunement | Core skills just need any attunement active |
| No Requirement | Basic skills always available |

---

## Skill Categories

### Core Skills (No Attunement Required)

Always available to all players.

#### Mana Category
| Skill | Max Level | Effect | Description |
|-------|-----------|--------|-------------|
| Mana Well | 10 | +100 max mana per level | Increases your mana reservoir |
| Mana Flow | 10 | +1 regen/hour per level | Faster mana regeneration |
| Elemental Attunement | 10 | +50 element cap per level | Store more elemental mana |

#### Study Category
| Skill | Max Level | Effect | Description |
|-------|-----------|--------|-------------|
| Quick Learner | 10 | +10% study speed per level | Learn faster |
| Focused Mind | 10 | -5% study cost per level | Learn cheaper |
| Knowledge Retention | 3 | +20% progress saved on cancel | Don't lose study progress |
| Meditation Focus | 1 | Up to 2.5x regen after 4hr meditating | Enhanced meditation |

#### Research Category (Long Study Times)
| Skill | Max Level | Effect | Description |
|-------|-----------|--------|-------------|
| Mana Tap | 1 | +1 mana/click | Better clicking |
| Mana Surge | 1 | +3 mana/click | Requires Mana Tap |
| Mana Spring | 1 | +2 mana regen | Passive bonus |
| Deep Trance | 1 | 6hr meditation = 3x regen | Requires Meditation |
| Void Meditation | 1 | 8hr meditation = 5x regen | Requires Deep Trance |

### Enchanter Skills (Requires Enchanter Attunement)

#### Enchanting Category
| Skill | Max Level | Effect | Attunement Req |
|-------|-----------|--------|----------------|
| Enchanting | 10 | Unlocks enchantment design | Enchanter 1 |
| Efficient Enchant | 5 | -5% capacity cost per level | Enchanter 2 |
| Disenchanting | 3 | +20% mana recovery per level | Enchanter 1 |
| Enchant Speed | 5 | -10% enchant time per level | Enchanter 1 |
| Essence Refining | 5 | +10% effect power per level | Enchanter 2 |

#### Effect Research Category
Research skills unlock enchantment effects. All are level 1 only and require Enchanter attunement.

**Tier 1 Research (Basic Spells)**
- Mana Spell Research → Mana Strike enchantment
- Fire Spell Research → Ember Shot, Fireball enchantments
- Water Spell Research → Water Jet, Ice Shard enchantments
- Air Spell Research → Gust, Wind Slash enchantments
- Earth Spell Research → Stone Bullet, Rock Spike enchantments
- Light Spell Research → Light Lance, Radiance enchantments
- Dark Spell Research → Shadow Bolt, Dark Pulse enchantments
- Death Research → Drain enchantment

**Tier 2 Research (Advanced Spells)** - Requires Enchanter 3
- Advanced Fire/Water/Air/Earth Research
- Advanced Light/Dark Research

**Tier 3 Research (Master Spells)** - Requires Enchanter 5
- Master Fire/Water/Earth Research

**Compound Mana Research** - Requires parent element research
- Metal Spell Research (Fire + Earth)
- Sand Spell Research (Earth + Water)
- Lightning Spell Research (Fire + Air)
- Plus Advanced/Master variants

**Utility Research**
- Transference Spell Research
- Damage Effect Research
- Mana Effect Research
- Utility Effect Research

### Invoker Skills (Requires Invoker Attunement)

#### Pact Category
| Skill | Max Level | Effect | Attunement Req |
|-------|-----------|--------|----------------|
| Pact Mastery | 5 | +10% pact bonus per level | Invoker 1 |
| Guardian Insight | 3 | See guardian weaknesses | Invoker 2 |
| Pact Efficiency | 3 | -10% pact ritual cost | Invoker 2 |

### Fabricator Skills (Requires Fabricator Attunement)

#### Golemancy Category
| Skill | Max Level | Effect | Attunement Req |
|-------|-----------|--------|----------------|
| Golem Mastery | 5 | +10% golem damage per level | Fabricator 2 |
| Golem Efficiency | 5 | +5% attack speed per level | Fabricator 2 |
| Golem Longevity | 3 | +1 floor duration per level | Fabricator 3 |
| Golem Siphon | 3 | -10% maintenance per level | Fabricator 3 |
| Advanced Golemancy | 1 | Unlock hybrid golem recipes | Fabricator 5 |
| Golem Resonance | 1 | +1 golem slot at max level | Fabricator 8 |

### Ascension Skills (Require Any Attunement Level 5+)

| Skill | Max Level | Effect | Requirement |
|-------|-----------|--------|-------------|
| Insight Harvest | 5 | +10% insight per level | Any attunement 5 |
| Temporal Memory | 3 | Keep 1 spell per level across loops | Any attunement 5 |

---

## Tier Up Requirements

Each tier requires specific attunement levels:

### Core Skills (Mana, Study)
| Tier | Requirement |
|------|-------------|
| 1→2 | Any attunement level 3 |
| 2→3 | Any attunement level 5 |
| 3→4 | Any attunement level 7 |
| 4→5 | Any attunement level 10 |

### Enchanter Skills
| Tier | Requirement |
|------|-------------|
| 1→2 | Enchanter level 3 |
| 2→3 | Enchanter level 5 |
| 3→4 | Enchanter level 7 |
| 4→5 | Enchanter level 10 |

### Fabricator Skills (Golemancy)
| Tier | Requirement |
|------|-------------|
| 1→2 | Fabricator level 3 |
| 2→3 | Fabricator level 5 |
| 3→4 | Fabricator level 7 |
| 4→5 | Fabricator level 10 |

### Hybrid Skills (Multiple Attunements)
| Tier | Requirement |
|------|-------------|
| 1→2 | Both attunements level 3 |
| 2→3 | Both attunements level 5 |
| etc. | Both attunements leveled together |

---

## Upgrade Tree Design Principles

### Branching Paths
Each skill's upgrade tree should:
1. Offer meaningful choices that change playstyle
2. Allow players to specialize or generalize
3. Provide trade-offs (gain X, lose Y)
4. Scale with future milestone choices

### Upgrade Categories

**Multiplier Upgrades**: Increase the base effect
- Example: "+25% max mana" → "+50% max mana"

**Bonus Upgrades**: Add flat bonuses
- Example: "+0.5 regen" → "+1 regen"

**Special Mechanics**: Unique behaviors
- Example: "Mana Cascade" (+0.1 regen per 100 max mana)
- Example: "Steady Stream" (immune to incursion regen penalty)

**Trade-offs**: Risk/reward
- Example: "+20% max mana, -10% regen"
- Example: "+50% damage when below 50% mana"

### Upgrade Persistence
- **Milestone upgrades persist through tier-ups**
- Tier 2 starts with all Tier 1's chosen upgrades
- New tier offers new upgrade paths

---

## Banned Effects

The following effects are **NOT allowed** in skill upgrades:

| Banned Effect | Reason |
|---------------|--------|
| Lifesteal | Player cannot take damage |
| Healing | Player cannot take damage |
| Life/Blood/Wood/Mental/Force mana | Removed elements |
| Execution effects | Instant kills bypass gameplay |
| Instant finishing | Skip mechanics |
| Direct spell damage bonuses | Spells only via weapons |

---

## Removed Skills

The following skills have been removed because the player cannot cast offensive spells directly:

| Removed Skill | Reason |
|---------------|--------|
| Combat Training | No direct spell casting |
| Arcane Fury | Combat damage bonus |
| Precision | Crit chance for spells |
| Quick Cast | Spell cast speed |
| Elemental Mastery | Elemental damage bonus |
| Spell Echo | Spell mechanics |
| Guardian Bane | Direct damage to guardians |

---

## Implementation Notes

### Study Cost Formula
```
cost = baseCost * (currentLevel + 1) * tier * costMultiplier
```

### Study Time Formula
```
time = baseStudyTime * tier / studySpeedMultiplier
```

### Tier Multiplier
```
tierMultiplier = 10^(tier - 1)
```
- Tier 1: 1x
- Tier 2: 10x
- Tier 3: 100x
- Tier 4: 1000x
- Tier 5: 10000x

---

## Example: Complete Skill Progression

### Mana Well Journey

1. **Study Mana Well** → Level 1 (+100 max mana)
2. **Continue studying** → Level 2-4 (+400 more max mana)
3. **Level 5 Milestone** → Choose "Expanded Capacity" (+25% max mana)
4. **Continue studying** → Level 6-9 (+400 more max mana)
5. **Level 10 Milestone** → Choose "Deep Reservoir" (upgrades Expanded Capacity to +50%)
6. **Tier Up** → Mana Well becomes "Deep Reservoir" (Tier 2)
7. **Continue at Tier 2** → Level 1-5 with 10x multiplier
8. **New upgrades available** at Tier 2 milestones

Total effect at Tier 2, Level 5:
- Base: 500 * 10 = 5000 max mana
- +50% from upgrades: +2500 max mana
- Total: 7500 max mana from one skill!