feat: add prestige system and skill upgrades with comprehensive documentation

2026-05-01 15:18:09 +02:00
parent 3691aa4acc
commit 03815f27ee
52 changed files with 4056 additions and 873 deletions
@@ -0,0 +1,165 @@
+# Task 15: Add Mana-Type Capacity Enchantment Effects Per Unlocked Mana Type
+
+## Context Summary
+
+### 1. Current Enchantment Effects for Mana Capacity
+
+**Location**: `/home/user/repos/Mana-Loop/src/lib/game/data/enchantments/mana-effects.ts`
+
+Current mana capacity effects (in `MANA_EFFECTS`):
+- `mana_cap_50` - +50 maximum mana (max 3 stacks)
+- `mana_cap_100` - +100 maximum mana (max 3 stacks)
+- `weapon_mana_cap_20` - +20 weapon mana capacity (max 5 stacks)
+- `weapon_mana_cap_50` - +50 weapon mana capacity (max 3 stacks)
+- `weapon_mana_cap_100` - +100 weapon mana capacity (max 2 stacks)
+
+**Element Capacity Effects**: There are currently NO per-type element capacity enchantment effects. The `elementCap` stat exists in `ComputedEffects` (in `upgrade-effects.ts`) and is applied via:
+- `elementCapBonus` - additive bonus to element max
+- `elementCapMultiplier` - multiplier for element max
+
+These apply globally to ALL elements equally (see `computeElementMax` in `store.ts`).
+
+### 2. Mana Types That Are Unlockable
+
+**Location**: `/home/user/repos/Mana-Loop/src/lib/game/constants/elements.ts`
+
+**Base Elements** (cat: "base"):
+- `fire` - Fire 🔥
+- `water` - Water 💧
+- `air` - Air 🌬️
+- `earth` - Earth ⛰️
+- `light` - Light ☀️
+- `dark` - Dark 🌑
+- `death` - Death 💀
+
+**Utility Elements** (cat: "utility"):
+- `transference` - Transference 🔗 (ALREADY UNLOCKED by default in `BASE_UNLOCKED_ELEMENTS`)
+
+**Composite Elements** (cat: "composite", require recipe to craft):
+- `metal` - Metal ⚙️ (recipe: fire + earth)
+- `sand` - Sand ⏳ (recipe: earth + water)
+- `lightning` - Lightning ⚡ (recipe: fire + air)
+
+**Exotic Elements** (cat: "exotic", require complex recipes):
+- `crystal` - Crystal 💎 (recipe: sand + sand + light)
+- `stellar` - Stellar ⭐ (recipe: fire + fire + light)
+- `void` - Void 🕳️ (recipe: dark + dark + death)
+
+**Total unlockable mana types**: 12 (all except `transference` which starts unlocked)
+
+### 3. How to Add Per-Type Capacity Effects
+
+**Current Effect System Architecture**:
+
+1. **Effect Definition** (`EnchantmentEffectDef` in `/src/lib/game/data/enchantment-types.ts`):
+   - Effects have a `stat` field that identifies what they modify
+   - Stats like `maxMana`, `regen`, `clickMana`, `elementCap` are supported
+   - Effects can be of type: `bonus` (additive), `multiplier`, or `special`
+
+2. **Current Element Cap System** (`/src/lib/game/upgrade-effects.ts` and `/src/lib/game/effects.ts`):
+   - `elementCapBonus` - additive bonus in `ComputedEffects`
+   - `elementCapMultiplier` - multiplier in `ComputedEffects`
+   - Applied in `computeElementMax()` in `store.ts`:
+     ```typescript
+     export function computeElementMax(state, effects?): number {
+       const pu = state.prestigeUpgrades;
+       const base = 10 + (state.skills.elemAttune || 0) * 50 + (pu.elementalAttune || 0) * 25;
+       if (effects) {
+         return Math.floor((base + effects.elementCapBonus) * effects.elementCapMultiplier);
+       }
+       return base;
+     }
+     ```
+
+3. **Approach to Add Per-Type Capacity Effects**:
+
+   **Option A: Extend the stat system with per-element prefixes**
+   - Add new stats like `elementCap_fire`, `elementCap_water`, etc.
+   - Modify `computeElementMax` to accept element parameter
+   - Modify `computeAllEffects` to handle per-element bonuses
+   
+   **Option B: Use a single stat with element metadata (Recommended)**
+   - Add effects with stat format: `elementCap_fire`, `elementCap_water`, etc.
+   - In `computeEquipmentEffects`, parse the element from stat name
+   - Store per-element bonuses in a `Record<string, number>` map
+   - Modify `computeElementMax` to accept element and look up per-element bonus
+   
+   **Option C: Add a new effect type for element-specific bonuses**
+   - Add new effect structure: `{ type: 'elementBonus', element: string, stat: 'capacity', value: number }`
+   - Requires modifying `EnchantmentEffectDef` type
+
+4. **Implementation Steps** (using Option B):
+   
+   a. **Define new enchantment effects** in `mana-effects.ts`:
+   ```typescript
+   fire_cap_10: {
+     id: 'fire_cap_10',
+     name: 'Fire Reservoir',
+     description: '+10 Fire mana capacity',
+     category: 'mana',
+     baseCapacityCost: 25,
+     maxStacks: 5,
+     allowedEquipmentCategories: MANA_EQUIPMENT,
+     effect: { type: 'bonus', stat: 'elementCap_fire', value: 10 }
+   }
+   // Repeat for each element: water, air, earth, light, dark, death, metal, sand, lightning, crystal, stellar, void
+   ```
+
+   b. **Update `ComputedEffects`** in `upgrade-effects.ts` to add per-element storage:
+   ```typescript
+   export interface ComputedEffects {
+     // ... existing fields
+     perElementCapBonus: Record<string, number>;  // New: per-element capacity bonuses
+   }
+   ```
+
+   c. **Update `computeEquipmentEffects`** in `effects.ts` to parse element-specific stats:
+   ```typescript
+   // In the bonus processing:
+   if (effect.stat.startsWith('elementCap_')) {
+     const element = effect.stat.replace('elementCap_', '');
+     bonuses.perElementCapBonus[element] = (bonuses.perElementCapBonus?.[element] || 0) + effect.value * ench.stacks;
+   }
+   ```
+
+   d. **Update `computeElementMax`** in `store.ts` to use per-element bonuses:
+   ```typescript
+   export function computeElementMax(state, effects?, element?: string): number {
+     const base = 10 + (state.skills.elemAttune || 0) * 50 + ...;
+     if (effects) {
+       let bonus = effects.elementCapBonus; // Global bonus
+       if (element && effects.perElementCapBonus?.[element]) {
+         bonus += effects.perElementCapBonus[element];
+       }
+       return Math.floor((base + bonus) * effects.elementCapMultiplier);
+     }
+     return base;
+   }
+   ```
+
+   e. **Update `unlockElement`** in `store.ts` to check for per-element capacity bonuses when unlocking
+
+5. **Effect Unlocking**: New effects should be unlocked via:
+   - `BASE_UNLOCKED_EFFECTS` - effects available from game start
+   - `EFFECT_RESEARCH_MAPPING` - effects unlocked by leveling specific skills
+   - `ENCHANTING_UNLOCK_EFFECTS` - effects unlocked by leveling enchanting skill
+
+### 4. Key Files to Modify
+
+1. `/src/lib/game/data/enchantments/mana-effects.ts` - Add per-element capacity effects
+2. `/src/lib/game/upgrade-effects.ts` - Update `ComputedEffects` interface, add per-element cap handling
+3. `/src/lib/game/effects.ts` - Update `computeEquipmentEffects` to parse element-specific stats
+4. `/src/lib/game/store.ts` - Update `computeElementMax` to accept element parameter and use per-element bonuses
+5. `/src/lib/game/constants/index.ts` or relevant constants file - Add new effects to unlockable lists if needed
+
+### 5. Allowed Equipment Categories
+
+For reference, from `enchantment-types.ts` and existing effects:
+- `MANA_EQUIPMENT: EquipmentCategory[] = ['caster', 'catalyst', 'head', 'body', 'accessory']`
+- Per-type capacity effects should likely use `MANA_EQUIPMENT` or similar
+
+### 6. Existing Related Special Effect
+
+`ELEMENTAL_AFFINITY` special effect (`SPECIAL_EFFECTS.ELEMENTAL_AFFINITY`):
+- When unlocking a new element, starts with 10 capacity instead of 0
+- This is already implemented in `unlockElement` in `store.ts`