Mana-Loop/docs/skills.md

# Mana Loop - Complete Skill System Documentation

## Table of Contents
1. [Overview](#overview)
2. [Core Mechanics](#core-mechanics)
3. [Skill Categories](#skill-categories)
4. [All Skills Reference](#all-skills-reference)
5. [Upgrade Trees](#upgrade-trees)
6. [Tier System](#tier-system)
7. [Banned Content](#banned-content)

---

## Overview

The skill system in Mana Loop provides deep character customization through a branching upgrade tree system. Skills are organized by attunement, with each attunement granting access to specific skill categories.

### Skill Level Types

| Max Level | Description | Example Skills |
|-----------|-------------|----------------|
| 10 | Standard skills with full upgrade trees | Mana Well, Mana Flow, Enchanting |
| 5 | Specialized skills with limited upgrades | Efficient Enchant, Golem Mastery |
| 3 | Focused skills with no upgrades | Knowledge Retention, Golem Longevity |
| 1 | Effect research skills (unlock only) | All research skills |

---

## Core Mechanics

### 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 Cost Formula
```
cost = baseCost × (currentLevel + 1) × tier × costMultiplier
```

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

### Milestone Upgrades

At **levels 5 and 10**, you choose **1 upgrade** from an upgrade tree:
- Each skill has its own unique upgrade tree
- Trees have branching paths with prerequisites
- Choices are permanent for that tier
- Upgrades persist when tiering up

---

## Skill Categories

### Core Categories (No Attunement Required)

| Category | Icon | Description |
|----------|------|-------------|
| Mana | 💧 | Mana pool and regeneration |
| Study | 📚 | Learning speed and efficiency |
| Research | 🔮 | Permanent bonuses |
| Ascension | ⭐ | Loop-persisting benefits |

### Attunement Categories

| Category | Icon | Attunement | Description |
|----------|------|------------|-------------|
| Enchanting | ✨ | Enchanter | Enchantment design and efficiency |
| Effect Research | 🔬 | Enchanter | Unlock spell enchantments |
| Invocation | 💜 | Invoker | Pact-based abilities |
| Pact Mastery | 🤝 | Invoker | Guardian pact bonuses |
| Fabrication | ⚒️ | Fabricator | Crafting and construction |
| Golemancy | 🗿 | Fabricator | Golem summoning and control |

---

## All Skills Reference

### Mana Skills (Core)

| Skill | Max | Effect | Base Cost | Study Time |
|-------|-----|--------|-----------|------------|
| Mana Well | 10 | +100 max mana/level | 100 | 4h |
| Mana Flow | 10 | +1 regen/hour/level | 150 | 5h |
| Elemental Attunement | 10 | +50 element cap/level | 200 | 4h |
| Mana Overflow | 5 | +25% click mana/level | 400 | 6h |

**Prerequisites:**
- Mana Overflow: Mana Well 3

### Study Skills (Core)

| Skill | Max | Effect | Base Cost | Study Time |
|-------|-----|--------|-----------|------------|
| Quick Learner | 10 | +10% study speed/level | 250 | 4h |
| Focused Mind | 10 | -5% study cost/level | 300 | 5h |
| Meditation Focus | 1 | Up to 2.5x regen after 4hrs | 400 | 6h |
| Knowledge Retention | 3 | +20% progress saved on cancel/level | 350 | 5h |

### Research Skills (Core)

| Skill | Max | Effect | Base Cost | Study Time |
|-------|-----|--------|-----------|------------|
| Mana Tap | 1 | +1 mana/click | 300 | 12h |
| Mana Surge | 1 | +3 mana/click | 800 | 36h |
| Mana Spring | 1 | +2 mana regen | 600 | 24h |
| Deep Trance | 1 | 6hr meditation = 3x regen | 900 | 48h |
| Void Meditation | 1 | 8hr meditation = 5x regen | 1500 | 72h |

**Prerequisites:**
- Mana Surge: Mana Tap 1
- Deep Trance: Meditation 1
- Void Meditation: Deep Trance 1

### Ascension Skills (Any Attunement)

| Skill | Max | Effect | Base Cost | Study Time | Attunement Req |
|-------|-----|--------|-----------|------------|----------------|
| Insight Harvest | 5 | +10% insight/level | 1000 | 20h | Any level 5+ |
| Temporal Memory | 3 | Keep 1 spell/level across loops | 2000 | 36h | Any level 5+ |
| Guardian Bane | 3 | +20% dmg vs guardians/level | 1500 | 30h | Invoker 1 |

### Enchanting Skills (Enchanter)

| Skill | Max | Effect | Base Cost | Study Time | Attunement Req |
|-------|-----|--------|-----------|------------|----------------|
| Enchanting | 10 | Unlocks enchantment design | 200 | 5h | Enchanter 1 |
| Efficient Enchant | 5 | -5% capacity cost/level | 350 | 6h | Enchanter 2 |
| Disenchanting | 3 | +20% mana recovery/level | 400 | 6h | Enchanter 1 |
| Enchant Speed | 5 | -10% enchant time/level | 300 | 4h | Enchanter 1 |
| Scroll Crafting | 3 | Store enchantment designs | 500 | 8h | Enchanter 3 |
| Essence Refining | 5 | +10% effect power/level | 450 | 7h | Enchanter 2 |

**Prerequisites:**
- Efficient Enchant: Enchanting 3
- Disenchanting: Enchanting 2
- Enchant Speed: Enchanting 2
- Scroll Crafting: Enchanting 5
- Essence Refining: Enchanting 4

### Golemancy Skills (Fabricator)

| Skill | Max | Effect | Base Cost | Study Time | Attunement Req |
|-------|-----|--------|-----------|------------|----------------|
| Golem Mastery | 5 | +10% golem damage/level | 300 | 6h | Fabricator 2 |
| Golem Efficiency | 5 | +5% attack speed/level | 350 | 6h | Fabricator 2 |
| Golem Longevity | 3 | +1 floor duration/level | 500 | 8h | Fabricator 3 |
| Golem Siphon | 3 | -10% maintenance/level | 400 | 8h | Fabricator 3 |
| Advanced Golemancy | 1 | Unlock hybrid recipes | 800 | 16h | Fabricator 5 |
| Golem Resonance | 1 | +1 golem slot | 1200 | 24h | Fabricator 8 |

**Prerequisites:**
- Advanced Golemancy: Golem Mastery 3
- Golem Resonance: Golem Mastery 5

### Effect Research Skills (Enchanter)

All effect research skills are **max level 1** and unlock specific enchantment effects.

#### Tier 1 Research (Basic Spells)
| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Mana Spell Research | Mana Strike enchantment | 4h |
| Fire Spell Research | Ember Shot, Fireball | 6h |
| Water Spell Research | Water Jet, Ice Shard | 6h |
| Air Spell Research | Gust, Wind Slash | 6h |
| Earth Spell Research | Stone Bullet, Rock Spike | 6h |
| Light Spell Research | Light Lance, Radiance | 8h |
| Dark Spell Research | Shadow Bolt, Dark Pulse | 8h |
| Death Research | Drain enchantment | 8h |

#### Tier 2 Research (Advanced Spells)
Requires Enchanter 3+ and parent element research.

| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Advanced Fire Research | Inferno, Flame Wave | 12h |
| Advanced Water Research | Tidal Wave, Ice Storm | 12h |
| Advanced Air Research | Hurricane, Wind Blade | 12h |
| Advanced Earth Research | Earthquake, Stone Barrage | 12h |
| Advanced Light Research | Solar Flare, Divine Smite | 14h |
| Advanced Dark Research | Void Rift, Shadow Storm | 14h |

#### Tier 3 Research (Master Spells)
Requires Enchanter 5+ and advanced research.

| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Master Fire Research | Pyroclasm | 24h |
| Master Water Research | Tsunami | 24h |
| Master Earth Research | Meteor Strike | 26h |

#### Compound Element Research
Requires parent element research + Enchanter 3+.

| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Metal Spell Research | Metal Shard, Iron Fist | 6h |
| Sand Spell Research | Sand Blast, Sandstorm | 6h |
| Lightning Spell Research | Spark, Lightning Bolt | 6h |
| Advanced Metal Research | Steel Tempest | 12h |
| Advanced Sand Research | Desert Wind | 12h |
| Advanced Lightning Research | Chain Lightning, Storm Call | 12h |
| Master Metal Research | Furnace Blast | 26h |
| Master Sand Research | Dune Collapse | 26h |
| Master Lightning Research | Thunder Strike | 26h |

#### Utility Research

| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Transference Spell Research | Transfer Strike, Mana Rip | 5h |
| Advanced Transference Research | Essence Drain | 12h |
| Master Transference Research | Soul Transfer | 26h |

#### Effect Research

| Skill | Unlocks | Study Time |
|-------|---------|------------|
| Damage Effect Research | Minor/Moderate Power, Amplification | 5h |
| Combat Effect Research | Sharp Edge, Swift Casting | 6h |
| Mana Effect Research | Mana Reserve, Trickle, Mana Tap | 4h |
| Advanced Mana Research | Mana Reservoir, Stream, River | 8h |
| Utility Effect Research | Meditative Focus, Quick Study | 6h |
| Special Effect Research | Echo Chamber, Siphoning, Bane | 10h |
| Overpower Research | Overpower effect | 12h |

---

## Upgrade Trees

### Mana Well Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Expanded Capacity (+25% max mana)
│   └── Level 10: Deep Reservoir (+50% max mana) [replaces]
│
├── Natural Spring (+0.5 regen/hour)
│   └── Level 10: Flowing Spring (+1.5 regen) [replaces]
│
├── Mana Threshold (+30% max mana, -10% regen)
│   └── Level 10: Mana Conversion (5% max → click bonus)
│
└── Desperate Wells (+50% regen when below 25% mana)
    └── Level 10: Panic Reserve (+100% regen below 10%)
```

**Level 10 Additional Choices:**
- Mana Echo (10% chance double mana from clicks)
- Emergency Reserve (Keep 10% mana on loop reset)
- Deep Wellspring (+50% meditation efficiency)

#### Tier 2 Upgrades (Deep Reservoir)
- Abyssal Depth (+50% max mana)
- Ancient Well (+500 starting mana per loop)
- Mana Condense (+1% max per 1000 gathered)
- Deep Reserve (+0.5 regen per 100 max mana)
- Ocean of Mana (+1000 max mana)
- Mana Tide (Regen pulses ±50%)
- Void Storage (Store 150% max temporarily)
- Mana Core (0.5% max mana as regen)

---

### Mana Flow Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Rapid Flow (+25% regen speed)
│   └── Level 10: Mana Torrent (+50% regen above 75% mana)
│
├── Steady Stream (Immune to incursion penalty)
│   └── Level 10: Eternal Flow (Immune to all penalties)
│
├── Mana Cascade (+0.1 regen per 100 max mana)
│   └── Level 10: Mana Waterfall (+0.25 per 100 max) [replaces]
│
└── Mana Overflow (Raw mana can exceed max by 20%)
```

**Level 10 Additional Choices:**
- Ambient Absorption (+1 permanent regen)
- Flow Surge (Clicks boost regen for 1 hour)
- Flow Mastery (+10% mana from all sources)

---

### Elemental Attunement Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Expanded Attunement (+25% element cap)
│   └── Level 10: Element Master (+50% element cap) [replaces]
│
├── Elemental Surge (+15% elemental spell damage)
│   └── Level 10: Elemental Power (+30% damage) [replaces]
│
└── Elemental Affinity (New elements start with 10 capacity)
```

**Level 10 Additional Choices:**
- Elemental Resonance (Spell use restores element)
- Exotic Mastery (+20% exotic element damage)

---

### Quick Learner Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Deep Focus (+25% study speed)
│   └── Level 10: Deep Concentration (+50% speed) [replaces]
│
├── Quick Grasp (5% chance double study progress)
│   └── Level 10: Knowledge Echo (15% instant complete)
│
├── Parallel Study (Study 2 things at 50% speed each)
│
└── Quick Mastery (-20% time for final 3 levels)
```

**Level 10 Additional Choices:**
- Study Momentum (+5% speed per hour, max 50%)
- Knowledge Transfer (New skills start at 10% progress)

---

### Focused Mind Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Mind Efficiency (+25% cost reduction)
│   └── Level 10: Efficient Learning (-15% study cost) [replaces]
│
├── Mental Clarity (+10% speed when mana > 75%)
│   └── Level 10: Study Rush (First hour 2x speed)
│
└── Study Refund (25% mana back on completion)
    └── Level 10: Deep Understanding (+10% skill bonuses)
```

**Level 10 Additional Choices:**
- Chain Study (-5% cost per maxed skill)

---

### Enchanting Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Enchantment Capacity (+20% equipment capacity)
├── Swift Enchanting (-15% design time)
│
└── Quality Control (+10% effect power)
    └── Level 10: Perfect Refinement (+25% power) [replaces]
```

**Level 10 Additional Choices:**
- Enchantment Mastery (2 designs in progress)
- Mana Preservation (25% chance free enchant)

---

### Golem Mastery Upgrade Tree

#### Tier 1 Upgrades

**Level 5 Choices:**
```
├── Golem Power (+25% golem damage)
├── Golem Durability (+1 floor duration)
│
└── Efficient Summons (-20% summon cost)
    └── Level 10: Golem Siphon (-30% maintenance)
```

**Level 10 Additional Choices:**
- Golem Fury (+50% attack speed for first 2 floors)
- Golem Resonance (Golems share 10% damage)

---

### Other Skill Upgrade Trees

#### Mana Overflow (Max 5)
- **Level 5:** Click Surge (+50% click mana above 90% mana)
- **Tier 2 Level 5:** Mana Flood (+75% click mana above 75% mana)

#### Efficient Enchant (Max 5)
- **Level 5:** Thrifty Enchanter (+10% free enchant chance)
- **Tier 2 Level 5:** Optimized Enchanting (+25% free chance)

#### Enchant Speed (Max 5)
- **Level 5:** Hasty Enchanter (+25% speed for repeat designs)
- **Tier 2 Level 5:** Instant Designs (10% instant completion)

#### Essence Refining (Max 5)
- **Level 5:** Pure Essence (+25% power for tier 1 enchants)
- **Tier 2 Level 5:** Perfect Essence (+50% all enchant power)

#### Efficient Crafting (Max 5)
- **Level 5:** Batch Crafting (2 items at 75% speed each)
- **Tier 2 Level 5:** Mass Production (3 items at full speed)

#### Field Repair (Max 5)
- **Level 5:** Scavenge (Recover 10% materials from broken items)
- **Tier 2 Level 5:** Reclaim (Recover 25% materials)

#### Golem Efficiency (Max 5)
- **Level 5:** Rapid Strikes (+25% speed for first 3 floors)
- **Tier 2 Level 5:** Blitz Attack (+50% speed for first 5 floors)

#### Insight Harvest (Max 5)
- **Level 5:** Insight Bounty (+25% insight from guardians)
- **Tier 2 Level 5:** Greater Harvest (+50% insight from all sources)

---

## Tier System

### How Tiers Work

1. **Reach max level** (10 for most skills, 5 for specialized)
2. **Meet attunement requirements**
3. **Tier up** - Skill resets to level 1 with 10x power multiplier

### Tier Power Scaling

| Tier | Multiplier | Level 1 Power = |
|------|------------|-----------------|
| 1 | 1x | Base |
| 2 | 10x | Tier 1 Level 10 |
| 3 | 100x | Tier 2 Level 10 |
| 4 | 1000x | Tier 3 Level 10 |
| 5 | 10000x | Tier 4 Level 10 |

### Tier Up Requirements

#### 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 |

---

## Banned Content

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

| Banned Effect | Reason |
|---------------|--------|
| Lifesteal | Player cannot take damage |
| Healing (for player) | Player cannot take damage |
| Life/Blood/Wood/Mental/Force mana | Removed elements |
| Execution effects | Bypasses gameplay mechanics |
| Instant finishing | Skips mechanics |
| Direct spell damage bonuses | Spells only via weapons |
| Familiar system | Replaced by golemancy |

### Design Philosophy

1. **Player cannot take damage** - Only floors/enemies have HP
2. **No healing needed** - Player health doesn't exist
3. **Weapons matter** - Player attacks through enchanted weapons
4. **Golems fight** - Fabricator's constructs do the combat
5. **Enchantments empower** - Enchanter enhances equipment
6. **Pacts grant power** - Invoker makes deals with guardians

---

## Example Progression

### Mana Well Complete Journey

1. **Level 1-4:** +400 max mana (100 per level)
2. **Level 5:** Choose "Expanded Capacity" (+25% max)
   - Total: 500 base + 125 bonus = 625 max mana
3. **Level 6-9:** +400 more max mana
4. **Level 10:** Choose "Deep Reservoir" (replaces to +50%)
   - Total: 1000 base + 500 bonus = 1500 max mana
5. **Tier Up to Tier 2:** Mana Well becomes "Deep Reservoir"
6. **Tier 2 Level 1:** 100 × 10 = 1000 base (same as T1 L10)
7. **Tier 2 Level 5:** Choose "Abyssal Depth" (+50% max)
8. **Continue progression...**

### Total Power at Tier 2 Level 5:
- Base: 500 × 10 = 5000 max mana
- Upgrades: +50% from Tier 1 +50% from Tier 2 = +100%
- Total: 5000 × 2 = **10,000 max mana**