Mana-Loop/docs/task5/subtask_15_context.md

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:

     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:

   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:

   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:

   // 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:

   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