Mana-Loop/docs/task3/effects_audit_report.md

Effects & Skills Audit Report - Mana Loop Game

Date: 2025-01-27 (Updated) Auditor: Senior Next.js Developer / Game Logic Reviewer Scope: Effects (effects.ts, upgrade-effects.ts), Skills (constants/skills.ts, skill-evolution.ts), Enchantments (data/enchantments/), Implementation (store.ts, crafting-slice.ts)

Status: VERIFIED - Code inspection completed, issues confirmed in current codebase

---

1. Visual Inconsistencies (Effect/Skill UI)

1.1 Missing Visual Feedback for Skill Upgrade Effects

Issue	Location	Details
No visual indicator for active special effects	SkillsTab, StatsTab	Players can't see which special effects are active (e.g., manaCascade, eternalFlow). Only the perk name is shown, not the dynamic effect state
Missing upgrade tier indicators	SkillsTab	No visual distinction between Tier 1-5 skills in the UI. The evolution system has 5 tiers but UI doesn't reflect this
Per-mana-type capacity upgrades not shown clearly	SkillsTab, StatsTab	New per-mana-type skills (fireManaCap, waterManaCap, etc.) from Bug 9 are in the "mana" category but may not show which specific element types have been upgraded

1.2 Inconsistent Effect Display

Issue	Location	Details
Enchantment effect power not displayed	EquipmentTab	The enchantPower multiplier from skills (Essence Refining, Enchanting perks) is never shown to the player - BECAUSE IT'S NEVER COMPUTED
Element capacity breakdown missing	StatsTab	While Bug 14 added mana breakdown, it may not show the per-type capacity bonuses from new skills - BECAUSE THEY'RE NOT IMPLEMENTED

---

2. UX Friction Points (Skill/Enchantment Interactions)

2.1 Skill Study Cost Confusion

Issue	Location	Impact
Per-mana-type skills require element mana to study (Bug 9, 11) but this isn't clearly communicated	SkillsTab	Players may not understand why they need Fire mana to study "Fire Mana Capacity +10%"
Effect Research skills cost both Transference + element mana (Bug 11) but UI may not show both costs	SkillsTab	The cost field in SKILLS_DEF includes type: 'element' but only shows one element type, not both Transference + element

2.2 Enchantment Design Flow Issues

Issue	Location	Details
enchantPower multiplier never applied to enchantment effects	effects.ts:computeEquipmentEffects(), upgrade-effects.ts:computeEffects()	CONFIRMED CRITICAL BUG: The enchantPower stat is defined in 20+ skill perks but NEVER applied in any computation. Code inspection confirms: (1) ComputedEffects interface has NO enchantPower field, (2) computeEffects() switch statement has NO case for enchantPower, (3) computeEquipmentEffects() never multiplies enchantment values by enchantPower
No feedback when essenceRefining should apply	Entire enchantment system	The Essence Refining skill (max: 1, +10% enchantment effect power) is defined in constants/skills.ts:35 but the effect never triggers because enchantPower isn't implemented
EFFECT RESEARCH SKILLS (tier unlocks) may not actually unlock effects	constants/skills.ts, EFFECT_RESEARCH_MAPPING	Need to verify that studying researchFireSpells actually unlocks spell_emberShot and spell_fireball in the enchantment design UI

2.3 Dead Code / Never-Triggered Logic

Issue	Location	Details
enchantPower stat defined 20+ times but NEVER READ	skill-evolution.ts lines 794, 802, 817, 825, 840, 863, 871, 886, 916, 924, 939, 947, 962, 992, 1000, 1015, 1023, 1038, 1582, 1590	All these perks define { type: 'multiplier', stat: 'enchantPower', value: 0.05-1.50 } but nothing in upgrade-effects.ts or effects.ts reads this stat. COMPLETE DEAD CODE
essenceRefining skill has no effect	constants/skills.ts:35	Even if studied, the +10% enchantment effect power is never applied since enchantPower isn't implemented
elemAttune references may be obsolete	store.ts:340, skill-evolution.ts:1945-	The legacy elemAttune skill is still referenced in computeElementMax() but the new per-mana-type skills (fireManaCap, etc.) from Bug 9 should be what's used - BUT THEY'RE NOT INTEGRATED

---

3. Missing Feedback / Empty States (Skill/Enchantment Results)

3.1 Missing Validation Feedback

Issue	Location	Issue
Per-mana-type capacity upgrades DON'T WORK	store.ts:computeElementMax(), utils/mana-utils.ts	CONFIRMED: The computeElementMax() function (line 340) still uses state.skills.elemAttune instead of checking per-type skills. The new skills (fireManaCap, waterManaCap, etc.) from Bug 9 are DEFINED but NEVER APPLIED
No feedback when enchantment effect power bonus applies	Enchantment design/apply flow	Player doesn't know if their Essence Refining or Enchanting perks are affecting their enchantments - BECAUSE THEY DON'T

3.2 Missing Empty/Error States

Issue	Location	Issue
No error message when trying to study per-mana-type skill without required element mana	SkillsTab, store.ts:startStudying()	The game silently fails or shows generic "Not enough raw mana" message instead of specific element mana requirement
No feedback when trying to apply enchantment that costs more capacity than available	crafting-slice.ts:startApplying()	Just returns false without explaining why

---

4. Suggested Improvements (Priority: High / Medium / Low)

HIGH Priority

ID	Improvement	Components Affected	Rationale	Status
H1	Implement enchantPower multiplier in enchantment calculations	upgrade-effects.ts:computeEffects(), effects.ts:computeEquipmentEffects(), effects.ts:computeAllEffects()	CRITICAL BUG CONFIRMED: The enchantPower stat is defined in 20+ skill perks but NEVER applied. Need to: (1) Add enchantPower: number to ComputedEffects interface (default: 1.0), (2) Add case 'enchantPower': effects.enchantPower *= effect.value; break; in computeEffects(), (3) Apply enchantPower in computeEquipmentEffects() when calculating enchantment effect values, (4) Merge into UnifiedEffects via computeAllEffects()	NOT FIXED
H2	Fix computeElementMax to use per-mana-type skills (Bug 9)	store.ts:computeElementMax(), utils/mana-utils.ts, store/computed.ts	CONFIRMED BROKEN: The function (line 340) uses `state.skills.elemAttune
H3	Verify enchantment effect application uses unified effects	effects.ts, crafting-slice.ts	Ensure computeAllEffects() (which merges skill upgrades + equipment effects) is used everywhere, not just computeEquipmentEffects() or computeEffects() separately	NEEDS VERIFICATION

MEDIUM Priority

ID	Improvement	Components Affected	Rationale	Status
M1	Add visual indicators for active special effects	SkillsTab, StatsTab	Show which special effects are active (e.g., "Mana Cascade: +0.1 regen per 100 max mana") with tooltip explanations	NOT IMPLEMENTED
M2	Display per-mana-type capacity upgrades in UI	SkillsTab, StatsTab	Show which element types have capacity bonuses and their values. The new skills (fireManaCap, etc.) need clear UI representation - ONCE H2 IS FIXED	BLOCKED BY H2
M3	Fix elemAttune legacy code references	store.ts, utils/mana-utils.ts, store/computed.ts, skill-evolution.ts	Either (a) deprecate elemAttune and fully switch to per-mana-type skills, or (b) keep both with clear documentation. Currently elemAttune evolution path in skill-evolution.ts:1945- is potentially obsolete	NEEDS DECISION
M4	Add validation feedback for element mana costs	SkillsTab, store.ts:startStudying()	When studying skills that require element mana (Bug 9, 11), show clear error messages about which element mana is needed and how much	NOT IMPLEMENTED
M5	Add enchantPower display to Enchantment UI	EquipmentTab, Enchantment design/apply flow	Show player their current enchantment power multiplier from skills so they know the bonus is applying - ONCE H1 IS FIXED	BLOCKED BY H1
M6	Verify Effect Research skills actually unlock enchantment effects	constants/skills.ts, EFFECT_RESEARCH_MAPPING, Enchantment design UI	The mapping exists but need to verify studying researchFireSpells actually makes spell_emberShot and spell_fireball available in the UI	NEEDS VERIFICATION

LOW Priority

ID	Improvement	Components Affected	Rationale	Status
L1	Clean up dead code (unused effect stats)	skill-evolution.ts, upgrade-effects.ts	Either implement enchantPower (H1) or remove/mark as deprecated the 20+ dead perk definitions	BLOCKED BY H1
L2	Add unit tests for per-mana-type capacity	skills.test.ts, store.test.ts	Add tests verifying fireManaCap, waterManaCap, etc. properly increase the respective element's max capacity - ONCE H2 IS FIXED	BLOCKED BY H2
L3	Add unit tests for enchantPower when implemented	upgrade-effects.test.ts	Once H1 is fixed, add tests verifying enchantment effects are properly multiplied	BLOCKED BY H1
L4	Standardize effect stat naming	upgrade-effects.ts, effects.ts	Some stats use abbreviations (regen) while others use full names (maxMana). Consider standardizing	NICE TO HAVE

---

Summary of Critical Findings (VERIFIED)

Broken Logic (Doesn't Work as Intended) - CONFIRMED

1. enchantPower multiplier is NEVER applied (H1) - CONFIRMED IN CODE

• Files:
  • skill-evolution.ts: Defines 20+ perks with stat: 'enchantPower' (lines 794, 802, 817, 825, 840, 863, 871, 886, 916, 924, 939, 947, 962, 992, 1000, 1015, 1023, 1038, 1582, 1590)
  • upgrade-effects.ts:computeEffects(): Switch statement (lines ~260-300) has NO case for enchantPower
  • effects.ts:computeEquipmentEffects(): Never reads or applies enchantPower
• Impact:
  • Essence Refining skill (+10% enchantment effect power) has NO EFFECT
  • Enchanting talent tree perks (Artisan's Touch +10%, Greater Artisan +15%, etc.) are USELESS
  • Pact-Weaving perks (Essence Weave +15%, Divine Weave +25%, etc.) DON'T WORK
• Root Cause: The ComputedEffects interface has no enchantPower field, and computeEffects() doesn't handle it
• Fix Required:
  1. Add enchantPower: number to ComputedEffects interface (default: 1.0)
  2. Add case 'enchantPower': effects.enchantPower *= effect.value; break; in computeEffects()
  3. Apply enchantPower in computeEquipmentEffects() when calculating enchantment values
  4. Merge enchantPower into UnifiedEffects in effects.ts:computeAllEffects()

2. computeElementMax uses legacy elemAttune instead of new per-mana-type skills (H2) - CONFIRMED IN CODE

• Files:
  • store.ts:340: const base = 10 + (state.skills.elemAttune || 0) * 50 + (pu.elementalAttune || 0) * 25;
  • constants/skills.ts:8-21: Defines per-mana-type skills (fireManaCap, waterManaCap, etc.) with max: 10, base: 200-350
• Issue:
  • computeElementMax() still uses state.skills.elemAttune (legacy skill)
  • Per-mana-type skills (fireManaCap, etc.) are DEFINED BUT NEVER INTEGRATED into computeElementMax()
  • Players can study fireManaCap but it WON'T INCREASE fire mana capacity
• Fix Required: Rewrite computeElementMax() to:
  • Check per-mana-type skills: state.skills.fireManaCap, state.skills.waterManaCap, etc.
  • Apply their bonuses: Each level = +10% capacity (per skill description)
  • Either remove elemAttune reference or keep for backward compatibility

Incomplete Implementation - CONFIRMED

3. Per-mana-type capacity upgrades (Bug 9) are NOT integrated - CONFIRMED INCOMPLETE

• Files:
  • constants/skills.ts:8-21: Defines 13 per-mana-type skills (fireManaCap, waterManaCap, airManaCap, earthManaCap, lightManaCap, darkManaCap, deathManaCap, metalManaCap, sandManaCap, lightningManaCap, transferenceManaCap)
  • Each has desc: "+10% [element] mana capacity", max: 10, studyTime: 4-6
• Issue: No code in store.ts:computeElementMax() checks these skills
• Verification: Code inspection confirms computeElementMax() only checks elemAttune and elementalAttune prestige upgrade

4. essenceRefining skill has no effect - CONFIRMED

• File: constants/skills.ts:35: essenceRefining: { name: "Essence Refining", desc: "+10% enchantment effect power", ... max: 1 }
• Issue: Skill can be studied (costs 450 study time), but the +10% bonus is NEVER APPLIED because enchantPower isn't implemented
• Player Impact: Wasted time studying a skill that provides no benefit

Dead Code (Never Triggers) - CONFIRMED

5. enchantPower stat is defined 20+ times but NEVER read by any computation - CONFIRMED DEAD CODE

• Files: skill-evolution.ts lines 794, 802, 817, 825, 840, 863, 871, 886, 916, 924, 939, 947, 962, 992, 1000, 1015, 1023, 1038, 1582, 1590
• All these perks define { type: 'multiplier', stat: 'enchantPower', value: 0.05-1.50 } but:
  • upgrade-effects.ts:computeEffects() has NO case for enchantPower
  • effects.ts:computeEquipmentEffects() never multiplies enchantment values by enchantPower
• Dead perks include:
  • Enchanting tree: Artisan's Touch (+10%), Greater Artisan (+15%), Expert Artisan (+25%), etc.
  • Pact-Weaving tree: Essence Weave (+15%), Divine Weave (+25%), etc.

6. elemAttune skill evolution path is potentially obsolete - CONFIRMED

• File: skill-evolution.ts:1945- (SKILL_EVOLUTION_PATHS.elemAttune)
• Issue: With per-mana-type skills (Bug 9), the generic elemAttune evolution path may be obsolete
• Current state: computeElementMax() still uses state.skills.elemAttune so it's still functional, but the new per-mana-type skills (fireManaCap, etc.) are NOT integrated
• Recommendation: Either (a) deprecate elemAttune and fully switch to per-mana-type skills, or (b) keep both with clear documentation

---

Files Requiring Updates (Priority Order)

1. H1: Implement enchantPower in upgrade-effects.ts and effects.ts

   • Add enchantPower: number to ComputedEffects interface
   • Add case in computeEffects() switch statement
   • Apply in computeEquipmentEffects()
   • Merge into UnifiedEffects

2. H2: Fix computeElementMax in store.ts, utils/mana-utils.ts, store/computed.ts

   • Rewrite to check per-mana-type skills (fireManaCap, etc.)
   • Apply +10% per level to respective element capacity

3. H3: Verify unified effects usage in crafting-slice.ts

   • Ensure computeAllEffects() is used everywhere

4. M1: Add special effects display to SkillsTab/StatsTab

   • Show active special effects with tooltips

5. M2: Display per-mana-type upgrades in UI (blocked by H2)

6. M3: Clean up elemAttune legacy references / decide on deprecation

7. M4: Add validation feedback for element mana costs

8. M6: Verify Effect Research skills actually unlock enchantment effects

---

Additional Findings from Code Inspection

A. Missing enchantPower in ComputedEffects Interface

File: upgrade-effects.ts:20-45

• The ComputedEffects interface does NOT have an enchantPower field
• This is why computeEffects() can't process it - the field doesn't exist

B. computeElementMax Function Analysis

File: store.ts:335-345

export function computeElementMax(
  state: Pick<GameState, 'skills' | 'prestigeUpgrades' | 'skillUpgrades' | 'skillTiers'>,
  effects?: ComputedEffects
): number {
  const pu = state.prestigeUpgrades;
  const base = 10 + (state.skills.elemAttune || 0) * 50 + (pu.elementalAttune || 0) * 25;
  
  // Apply upgrade effects if provided
  if (effects) {
    return Math.floor((base + effects.elementCapBonus) * effects.elementCapMultiplier);
  }
  return base;
}

• Issue: Only checks elemAttune (legacy), not per-mana-type skills
• Missing: Checks for fireManaCap, waterManaCap, etc.

C. Essence Refining Perk Definition

File: skill-evolution.ts:794

createPerk('en_t1_l5_a', 'Artisan\'s Touch', '+10% Enchantment Power', 'A',
  { type: 'multiplier', stat: 'enchantPower', value: 0.10 }, false, 1.5, 5),

• This perk is defined but NEVER PROCESSED

D. Effect Research Skills - Need Verification

File: constants/skills.ts:46-82

• Defines many Effect Research skills (researchFireSpells, researchWaterSpells, etc.)
• EFFECT_RESEARCH_MAPPING maps them to effect IDs
• NEEDS VERIFICATION: That studying these skills actually unlocks the effects in the enchantment design UI

---

Testing Recommendations

For H1 (enchantPower implementation):

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

For H2 (per-mana-type skills):

1. Study fireManaCap to level 1 (+10% fire mana capacity)
2. Check fire mana max - should be base * 1.10
3. Study to level 10 (+100% fire mana capacity)
4. Check fire mana max - should be base * 2.0
5. Repeat for other elements (water, air, earth, etc.)

---

Notes

• The enchantPower issue is the MOST CRITICAL finding - it means the Essence Refining skill and Enchanting perks are completely useless
• The per-mana-type capacity upgrades (Bug 9) are NOT IMPLEMENTED despite being defined in constants/skills.ts
• The elemAttune skill evolution path in skill-evolution.ts may need to be updated or removed since per-mana-type skills replace its functionality
• Consider adding debug logging or a "Effects Debug" panel to verify which effects are active and their values
• PRIORITY: Fix H1 and H2 before next release - players are studying skills that provide NO BENEFIT