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

   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:

     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.