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