Redesign skill system with upgrade trees and tier progression

Major changes: - Created docs/skills.md with comprehensive skill system documentation - Rewrote skill-evolution.ts with new upgrade tree structure: - Upgrades organized in branching paths with prerequisites - Each choice can lead to upgraded versions at future milestones - Support for upgrade children and requirement chains - Added getBaseSkillId and generateTierSkillDef helper functions - Fixed getFloorElement to use FLOOR_ELEM_CYCLE.length - Updated test files to match current skill definitions - Removed tests for non-existent skills Skill system now supports: - Levels 1-10 for most skills, level 5 caps for specialized, level 1 for research - Tier up system: Tier N Level 1 = Tier N-1 Level 10 in power - Milestone upgrades at levels 5 and 10 with branching upgrade trees - Attunement requirements for skill access and tier up - Study costs and time for leveling
2026-04-03 11:08:58 +00:00
parent 9044d0ed61
commit b78c979647
61 changed files with 16863 additions and 630 deletions
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -0,0 +1,323 @@
+# 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!