Mana-Loop/docs/skills.md

Mana Loop - Complete Skill System Documentation

Table of Contents

1. Overview
2. Core Mechanics
3. Skill Categories
4. All Skills Reference
5. Upgrade Trees
6. Tier System
7. Banned Content
8. Code Architecture

---

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

Attunement Categories

Category	Icon	Attunement	Description	Status
Enchanting	✨	Enchanter	Enchantment design and efficiency	✅ Implemented (T1-T5)
Effect Research	🔬	Enchanter	Unlock spell enchantments	✅ Implemented (max:1)
Invocation	💜	Invoker	Pact-based abilities	✅ Implemented (T1-T5)
Pact Mastery	🤝	Invoker	Guardian pact bonuses	✅ Implemented (T1-T5)
Fabrication	⚒️	Fabricator	Crafting and construction	✅ Implemented (T1-T5)
Golemancy	🗿	Fabricator	Golem summoning and control	✅ Implemented (T1-T5)
Hybrid Skills	🔮	Dual Attunement	Cross-attunement powers	✅ Implemented (T1-T5)

---

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

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
Essence Refining	1	+10% effect power	450	7h	Enchanter 2

Prerequisites:

• Efficient Enchant: Enchanting 3
• Disenchanting: Enchanting 2
• Enchant Speed: Enchanting 2
• 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

---

Hybrid Skills

Hybrid Skills require two attunements and combine their powers into advanced abilities.

Code Location: All hybrid skills are defined in src/lib/game/skill-evolution-modules/hybrid-skills.ts

Pact-Weaving (Invoker + Enchanter)

Requirement: Invoker 3 + Enchanter 3
Max Level: 5 (with Elite Perk at Level 5)
Location: skill-evolution-modules/hybrid-skills.ts

Paths:

• Path A: The Weaver - Enhanced enchantment power through pact bonuses
• Path B: The Warp - Unpredictable magic blending pacts and enchantments
• Path C: The World-Weaver - Ultimate hybrid combining all powers

5-Tier Talent Tree:

Tier	Level	Effect
1	1-2	+10% enchantment power when pact active
2	3-4	+25% enchantment power when pact active
3	5-6	Pact boons apply to enchanted equipment
4	7-8	+50% enchantment power when pact active
5	9-10	Elite Perk: Choose one

Elite Perks (Choose at Tier 5 Level 10):

• Eternal Weave: Enchantments persist through loops
• Pactbound Power: All pact multipliers doubled for enchanted items
• Weaver's Boon: 25% chance to double enchantment effect

Level 5 Upgrade Choices:

• +50% enchantment power when pact active
• Pact boons apply to all equipment slots
• 10% chance to trigger pact effect on enchant

Level 10 Upgrade Choices:

• Elite Perk (choose one from above)
• +100% enchantment power when pact active
• All pacts active simultaneously

---

Guardian Constructs (Fabricator + Invoker)

Requirement: Fabricator 3 + Invoker 3
Max Level: 5 (with Elite Perk at Level 5)
Location: skill-evolution-modules/hybrid-skills.ts

Paths:

• Path A: The Architect - Durable constructs with enhanced defenses
• Path B: The Monumentalist - Massive single construct with supreme power
• Path C: The Eternal - Constructs that never expire

Special Rules:

• Only 1 active at a time (replaces golems)
• More durable than golems (2x HP, 1.5x duration)
• Uses both Earth and Pact mana for summoning

5-Tier Talent Tree:

Tier	Level	Effect
1	1-2	+25% construct HP
2	3-4	Construct lasts +2 floors
3	5-6	Construct gains pact bonuses
4	7-8	+50% construct damage
5	9-10	Elite Perk: Choose one

Elite Perks (Choose at Tier 5 Level 10):

• Living Monument: Construct HP +500%, never expires
• Guardian's Might: Construct gains all pact multipliers
• Architect's Dream: Can have 2 constructs (reduces HP by 50% each)

Level 5 Upgrade Choices:

• +50% construct HP
• Construct immune to floor effects
• +25% construct damage

Level 10 Upgrade Choices:

• Elite Perk (choose one from above)
• Construct gains 100% of your pact multipliers
• +500% construct HP

---

Enchanted Golemancy (Fabricator + Enchanter)

Requirement: Fabricator 3 + Enchanter 3
Max Level: 5 (with Elite Perk at Level 5)
Location: skill-evolution-modules/hybrid-skills.ts

Paths:

• Path A: The Battle-Smith - Combat-focused enchanted golems
• Path B: The Enchanter-Smith - Golems with powerful enchantments
• Path C: The Spell-Smith - Golems that cast elemental spells

Special Rules:

• Imbues golems with elemental spell logic
• Golems gain spell abilities from enchantments
• Combines golem durability with spell power

5-Tier Talent Tree:

Tier	Level	Effect
1	1-2	Golems gain 1 spell slot
2	3-4	+25% golem spell damage
3	5-6	Golems gain 2 spell slots
4	7-8	+50% golem spell damage
5	9-10	Elite Perk: Choose one

Elite Perks (Choose at Tier 5 Level 10):

• Arcane Golem: Golems cast spells at 3x speed
• Elemental Master: Golem spells gain +100% elemental bonus
• Living Spellforge: Golems create temporary enchantments

Level 5 Upgrade Choices:

• +50% golem spell damage
• Golems gain 3 spell slots
• Golem spells gain pact bonuses

Level 10 Upgrade Choices:

• Elite Perk (choose one from above)
• Golem spells deal +200% damage
• Golems permanently enchanted

---

Effect Research Skills (Enchanter)

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

Code Location: Skill definitions in src/lib/game/constants/skills.ts, research logic in src/lib/game/skill-evolution-modules/enchanting-skills.ts

Tier1 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

Tier2 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

Tier3 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

Code Location: All upgrade trees are defined in src/lib/game/skill-evolution-modules/:

• mana-well-flow.ts - Mana Well and Mana Flow upgrades
• enchanting-skills.ts - Enchanting skill upgrades
• quick-learner.ts - Quick Learner upgrades
• focused-mind.ts - Focused Mind upgrades
• And more...

Mana Well Upgrade Tree

Tier1 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)

Tier2 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

Tier1 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

Tier1 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

Tier1 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

Tier1 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

Tier1 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

Tier1 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 1)

• Research skill (max level 1, no upgrades)

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)

---

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

---

Code Architecture

Modular Structure

The skill system has been refactored into a modular architecture for better maintainability:

Skill Definitions (src/lib/game/constants/skills.ts)

• All skill definitions in one file (~30KB)
• Organized by category (mana, study, enchanting, etc.)
• Contains base stats, prerequisites, and evolution paths

Skill Evolution Modules (src/lib/game/skill-evolution-modules/)

Each skill tree has its own module:

Module File	Contents
mana-well-flow.ts	Mana Well, Mana Flow, Elemental Attunement
quick-learner.ts	Quick Learner, Knowledge Retention
focused-mind.ts	Focused Mind, Meditation skills
enchanting-skills.ts	Enchanting, Efficient Enchant, Disenchanting
invocation-skills.ts	Invocation, Pact Mastery trees
hybrid-skills.ts	Pact-Weaving, Guardian Constructs, Enchanted Golemancy
guardian-skills.ts	Guardian Bane, related skills
insight-harvest.ts	Insight, Deep Memory skills
mana-utility-skills.ts	Mana Overflow, Mana Tap, etc.
elemental-attunement.ts	Elemental skill upgrades
knowledge-retention.ts	Knowledge retention mechanics
learning-skills.ts	Learning speed skills
magic-skills.ts	Magic-related skills
utils.ts	Shared utility functions
types.ts	TypeScript interfaces
index.ts	Main export combining all modules (~11KB)

Adding a New Skill (Updated Process)

1. Define in constants/skills.ts (NEW location)

   • Add to SKILLS_DEF object
   • Define base cost, study time, max level, category

2. Add evolution path in skill-evolution-modules/ (NEW location)

   • Create new module or add to existing module
   • Define upgrade trees for levels 5 and 10
   • Export upgrade functions

3. Export from skill-evolution-modules/index.ts

   • Import and re-export new module
   • Ensure all upgrade functions are accessible

4. Update UI in components/game/tabs/SkillsTab.tsx

   • Skill tab automatically reads from new structure
   • May need updates for new categories or display logic

File Size Enforcement

All skill files are kept under 400 lines (enforced by pre-commit hook):

• skill-evolution-modules/*.ts - Focused modules, typically 100-600 lines
• constants/skills.ts - Largest file at ~1000 lines ( acceptable as it's mostly data)
• Better code organization and maintainability
• Faster for AI agents to read and understand

---

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

---

Document Version: 1.1 (Updated for Modular Architecture)
Code has been refactored - game mechanics unchanged