Anexim/Mana-Loop
1
1
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Updated docs
Build and Publish Mana Loop Docker Image / build-and-publish (push) Failing after 56s
Details

Browse Source
This commit is contained in:
n8n-gitea
2026-05-18 11:26:24 +02:00
parent 67bd5b4a86
commit 20c2ebd7b5
6 changed files with 308 additions and 1349 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+27 -11
View File
@@ -43,26 +43,42 @@ Use for 3+ sequential independent calls. Zero context from parent — paste ever
## Architecture
- **Stack:** Next.js 16, TS 5, Tailwind 4 + shadcn/ui, Zustand+persist, Vitest/Playwright, Bun
- **Active stores:** `src/lib/game/stores/{game,mana,combat,prestige,skill,ui}Store.ts`
- **Active stores:** `src/lib/game/stores/{game,mana,combat,prestige,discipline,ui}Store.ts`
- **Legacy (migrating):** `src/lib/game/store/` and `store-modules/`
- **Crafting:** 3-step flow — Design → Prepare → Apply via `crafting-actions/`
- **Skills v2:** `constants/skills-v2.ts` + `computeStats()` in effects
- **Effects:** All stat mods through `getUnifiedEffects()` — never read skill levels directly
- **Disciplines:** `data/disciplines/` + `stores/discipline-slice.ts` + `utils/discipline-math.ts`
- **Effects:** All stat mods through `getUnifiedEffects()` — discipline bonuses enter via `computeDisciplineEffects()`
### Adding Effects
1. `data/enchantment-effects.ts`
2. `effects.ts` → `computeEquipmentEffects()`
3. Access via `getUnifiedEffects(state)`
### Adding Skills
1. `constants/skills-v2.ts`
2. `computeStats()` mapping
### Adding Disciplines
1. Choose the correct data file under `data/disciplines/`:
- `base.ts` — available to all attunements
- `enchanter.ts` — requires Enchanter attunement
- `invoker.ts` — requires Invoker attunement
- `fabricator.ts` — requires Fabricator attunement
2. Define a `DisciplineDefinition` (see `types/disciplines.ts`):
- `statBonus.stat` must match a key consumed by `computeDisciplineEffects()`
- Set `difficultyFactor` and `scalingFactor` to control growth rate
- Add perks (`once`, `capped`, or `infinite`)
3. Re-export from `data/disciplines/index.ts` so it appears in `ALL_DISCIPLINES`
4. Add any new `statBonus.stat` keys to `discipline-effects.ts` → `computeDisciplineEffects()`
### Discipline Math (quick reference)
```
StatBonus = baseValue × (XP / scalingFactor)^0.65
ManaDrainPerTick = drainBase × (1 + (XP / difficultyFactor)^0.4)
```
- XP accrues every tick the discipline is active and mana drain is met
- `concurrentLimit` starts at 1 and expands by 1 per 500 total XP (max +3)
### Adding Spells
1. `constants/spells.ts`
2. `data/enchantment-effects.ts`
3. `constants/skills-v2.ts` research skill
4. `EFFECT_RESEARCH_MAPPING`
3. `EFFECT_RESEARCH_MAPPING`
## Banned
@@ -74,7 +90,7 @@ Lifesteal/healing, scroll crafting, ascension skills, LabTab, pause, mana types:
## Mana Types
**Base (7):** Fire 🔥 Water 💧 Air 🌬️ Earth ⛰️ Light ☀️ Dark 🌑 Death 💀
**Utility (1):** Transference 🔗
**Compound (3):** Fire+Earth=Metal, Earth+Water=Sand, Fire+Air=Lightning
**Base (7):** Fire 🔥 Water 💧 Air 🌬️ Earth ⛰️ Light ☀️ Dark 🌑 Death 💀
**Utility (1):** Transference 🔗
**Compound (3):** Fire+Earth=Metal, Earth+Water=Sand, Fire+Air=Lightning
**Exotic (3):** Sand+Sand+Light=Crystal, Fire+Fire+Light=Stellar, Dark+Dark+Death=Void
docs/GAME_BRIEFING.md
+278 -608
View File
File diff suppressed because it is too large Load Diff
docs/circular-deps.txt
+1 -1
View File
@@ -1,5 +1,5 @@
# Circular Dependencies
Generated: 2026-05-18T08:24:36.648Z
Generated: 2026-05-18T08:33:19.846Z
Found: 7 circular chain(s) — these MUST be fixed before modifying involved files.
1. Processed 151 files (1.4s) (37 warnings)
docs/dependency-graph.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"_meta": {
"generated": "2026-05-18T08:24:35.073Z",
"generated": "2026-05-18T08:33:18.234Z",
"description": "Import dependency graph for src/lib/game. Keys are files, values are arrays of files they import.",
"usage": "To find what a file affects, search for its path in the VALUES. To find what a file depends on, look at its KEY entry."
},
docs/project-structure.txt
+1 -2
View File
@@ -15,8 +15,7 @@ Mana-Loop/
│ ├── GAME_BRIEFING.md
│ ├── circular-deps.txt
│ ├── dependency-graph.json
│ ├── project-structure.txt
│ └── skills.md
│ └── project-structure.txt
├── e2e/
│ ├── combat.spec.ts
│ ├── enchanting.spec.ts
docs/skills.md
-726
View File
@@ -1,726 +0,0 @@
# 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)
8. [Code Architecture](#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) |
#### Skill State Management
Skill state is managed in the store layer:
- **New Modular Store:** `src/lib/game/stores/skillStore.ts` (~11KB) - Active skill state, studying, evolution
- **Legacy Slice:** `src/lib/game/store/skillSlice.ts` - Being migrated to `skillStore.ts`
- **Skill state includes:** `skills` (levels), `skillUpgrades` (chosen upgrades), `skillTiers` (current tier)
### 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*