Mana-Loop/docs/task3/essence_refining_findings.md

# Essence Refining Investigation Findings

## Bug 15: Essence Refining Effect Not Applied

### Executive Summary
The `Essence Refining` skill (and related `enchantPower` perks) are **NOT WORKING**. The skill sets up the `enchantPower` stat, but this stat is never applied to enchantment effects.

### Root Cause
1. **Skill Definition** (`/src/lib/game/constants/skills.ts`, line 22):
   - `essenceRefining` skill is defined with description "+10% enchantment effect power"
   - Max level: 1, so provides +10% when learned

2. **Perk Definitions** (`/src/lib/game/skill-evolution.ts`):
   - Multiple perks set `enchantPower` multiplier (e.g., `Essence Weave` +15%, `Greater Weave` +25%)
   - These perks correctly create effects with `{ type: 'multiplier', stat: 'enchantPower', value: 0.15 }`

3. **MISSING IMPLEMENTATION** (`/src/lib/game/upgrade-effects.ts`):
   - The `computeEffects()` function processes all upgrade effects
   - **`enchantPower` is NOT handled** in the switch statement (lines ~260-300)
   - The `ComputedEffects` interface does NOT have an `enchantPower` field

4. **MISSING APPLICATION** (`/src/lib/game/effects.ts`):
   - The `computeEquipmentEffects()` function processes enchantment effects
   - **`enchantPower` multiplier is NEVER applied** to enchantment values
   - Enchantment bonuses and multipliers are computed without any `enchantPower` scaling

### Enchantment Types Analysis

Based on `/src/lib/game/data/enchantments/`, here are all enchantment types and their compatibility:

#### 1. Spell Effects (`spell-effects.ts`)
- **Effect Type**: `spell` (grants ability to cast spells)
- **Compatible with Essence Refining**: NO - Spell effects just grant spell access, no numeric values to multiply
- **Examples**: `spell_fireball`, `spell_lightningBolt`, `spell_pyroclasm`

#### 2. Mana Effects (`mana-effects.ts`)
- **Effect Type**: `bonus` (for stats like `maxMana`, `regen`, `clickMana`, `weaponManaMax`, `weaponManaRegen`)
- **Compatible with Essence Refining**: YES - Bonus values should be multiplied
- **Examples**: `mana_cap_50` (+50 max mana), `mana_regen_1` (+1 regen), `weapon_mana_cap_20` (+20 weapon mana)

#### 3. Combat Effects (`combat-effects.ts`)
- **Effect Type**: `bonus` (for `baseDamage`, `critChance`) and `multiplier` (for `baseDamage`, `attackSpeed`)
- **Compatible with Essence Refining**: YES - Both bonus and multiplier values should be scaled
- **Examples**: `damage_5` (+5 damage), `damage_pct_10` (+10% damage), `crit_5` (+5% crit), `attack_speed_10` (+10% attack speed)

#### 4. Elemental Effects (`elemental-effects.ts`)
- **Effect Type**: `special` (for `fireBlade`, `frostBlade`, `lightningBlade`, `voidBlade`)
- **Compatible with Essence Refining**: PARTIAL - Special effects may have internal damage values that should be scaled, but currently the special effects system doesn't support numeric scaling
- **Examples**: `sword_fire`, `sword_frost`, `sword_lightning`, `sword_void`

#### 5. Defense Effects (`defense-effects.ts`)
- **Effect Type**: Currently empty
- **Compatible with Essence Refining**: N/A

#### 6. Utility Effects (`utility-effects.ts`)
- **Effect Type**: `multiplier` (for `meditationEfficiency`, `studySpeed`, `insightGain`)
- **Compatible with Essence Refining**: YES - Multiplier values should be scaled
- **Examples**: `meditate_10` (+10% meditation), `study_10` (+10% study speed), `insight_5` (+5% insight)

#### 7. Special Effects (`special-effects.ts`)
- **Effect Type**: `special` (for `spellEcho10`, `overpower`, `firstStrike`, `comboMaster`, `adrenalineRush`) and `multiplier` (for `guardianDamage`)
- **Compatible with Essence Refining**: PARTIAL - The `guardianDamage` multiplier can be scaled, but pure special effects cannot
- **Examples**: `spell_echo_10`, `guardian_dmg_10` (+10% guardian damage), `overpower_80`, `combo_master`

### Required Fix

To fix Bug 15, the following changes are needed:

1. **Add `enchantPower` to `ComputedEffects` interface** (`upgrade-effects.ts`):
   ```typescript
   export interface ComputedEffects {
     // ... existing fields ...
     enchantPower: number;  // Multiplier for enchantment effects (1.0 = 100%)
   }
   ```

2. **Handle `enchantPower` in `computeEffects()`** (`upgrade-effects.ts`):
   - Initialize `enchantPower: 1` in the default effects
   - Add case for `enchantPower` in the multiplier switch:
     ```typescript
     case 'enchantPower':
       effects.enchantPower *= effect.value;
       break;
     ```

3. **Apply `enchantPower` in `computeEquipmentEffects()`** (`effects.ts`):
   - Get `enchantPower` from `ComputedEffects` (via `upgradeEffects`)
   - Multiply bonus values by `enchantPower`
   - For multiplier effects, apply `enchantPower` to the base value before compounding

4. **Consider special effects**: For `special` type effects that have damage/effectiveness values, the special effect handling code needs to also respect `enchantPower`.

### Testing Recommendations
1. Learn `Essence Refining` skill (+10% enchantment power)
2. Apply a `+50 max mana` enchantment - should give +55 with skill
3. Apply a `+10% damage` enchantment - should give +11% with skill
4. Verify spell effects are NOT affected (they don't have numeric values)
5. Test with higher tier perks like `Essence Weave` (+15%) and `Greater Weave` (+25%)

### Files Requiring Modification
1. `/src/lib/game/upgrade-effects.ts` - Add `enchantPower` handling
2. `/src/lib/game/effects.ts` - Apply `enchantPower` to equipment effects
3. Potentially `/src/lib/game/data/enchantments/special-effects.ts` - If special effects need scaling

### Priority
**HIGH** - This is a core enchanting skill that players expect to work. Currently, players are spending time learning `Essence Refining` and choosing `enchantPower` perks with no benefit.