Mana-Loop/docs/task3/effects_audit_report.md

Effects & Skills Audit Report - Mana Loop Game

Date: 2025-01-26
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)

---

1. Visual Inconsistencies (for effects/skills 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
Element capacity breakdown missing	StatsTab	While Bug 14 added mana breakdown, it may not show the per-type capacity bonuses from new skills

---

2. UX Friction Points (for 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()	CRITICAL: The enchantPower stat (from Essence Refining skill and Enchanting perks) is defined but NEVER applied in any computation. Enchantment effects are calculated without this multiplier.
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 used

2.3 Dead Code / Never-Triggered Logic

Issue	Location	Details
enchantPower stat never read	upgrade-effects.ts, effects.ts	The stat enchantPower appears in 20+ perk definitions in skill-evolution.ts but is never read by computeEffects() or computeEquipmentEffects()
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 in compute functions	store.ts:340, utils/mana-utils.ts:30, store/computed.ts:51	The legacy elemAttune skill is still referenced but the new per-mana-type skills (fireManaCap, etc.) from Bug 9 should be what's used

---

3. Missing Feedback / Empty States (for skill/enchantment results)

3.1 Missing Validation Feedback

Issue	Location	Issue
No validation that per-mana-type capacity upgrades actually work	store.ts, utils/mana-utils.ts	Need to verify the new skills (fireManaCap, etc.) are properly increasing element capacity. The computeElementMax function still uses state.skills.elemAttune instead of checking per-type skills
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

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 (with priority: high / medium / low)

HIGH Priority

ID	Improvement	Components Affected	Rationale
H1	Implement enchantPower multiplier in enchantment calculations	effects.ts:computeEquipmentEffects(), upgrade-effects.ts:computeEffects()	CRITICAL BUG: The enchantPower stat is defined in 20+ skill perks but NEVER applied. Need to: (1) Add enchantPowerMultiplier to ComputedEffects and UnifiedEffects, (2) Apply it in computeEquipmentEffects() when calculating enchantment effect values, (3) Ensure Essence Refining skill (+10%) and Enchanting perks actually work
H2	Fix computeElementMax to use per-mana-type skills (Bug 9)	store.ts:computeElementMax(), utils/mana-utils.ts:computeElementMax(), store/computed.ts	The function still uses state.skills.elemAttune but should check individual per-mana-type skills (fireManaCap, waterManaCap, etc.) and apply their bonuses to the respective element's max capacity
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

MEDIUM Priority

ID	Improvement	Components Affected	Rationale
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
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
M3	Fix elemAttune legacy code references	store.ts, utils/mana-utils.ts, store/computed.ts	Remove or deprecated references to elemAttune skill since per-mana-type skills (Bug 9) should handle this now. Or ensure backward compatibility
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
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

LOW Priority

ID	Improvement	Components Affected	Rationale
L1	Clean up dead code (unused effect stats)	skill-evolution.ts, upgrade-effects.ts	Remove or mark as deprecated the enchantPower stat if not being used, or add a TODO comment explaining the implementation plan
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
L3	Add unit tests for enchantPower when implemented	upgrade-effects.test.ts	Once H1 is fixed, add tests verifying enchantment effects are properly multiplied
L4	Standardize effect stat naming	upgrade-effects.ts, effects.ts	Some stats use abbreviations (regen) while others use full names (maxMana). Consider standardizing

---

Summary of Critical Findings

Broken Logic (Doesn't Work as Intended)

1. enchantPower multiplier is NEVER applied (H1)

   • Files: skill-evolution.ts (defines perks with stat: 'enchantPower'), but upgrade-effects.ts:computeEffects() doesn't have a case for enchantPower
   • Impact: Essence Refining skill (+10% enchantment effect power) and all Enchanting tier perks that give enchantPower are completely useless
   • Fix: Add enchantPowerMultiplier to ComputedEffects, apply it in computeEquipmentEffects() when calculating final enchantment effect values

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

   • Files: store.ts:340, utils/mana-utils.ts:30, store/computed.ts:51-52
   • Code: const base = 10 + (state.skills.elemAttune || 0) * 50 + ...
   • Issue: The new per-mana-type skills (fireManaCap, waterManaCap, etc.) from Bug 9 are defined but computeElementMax doesn't check them
   • Fix: Either (a) make the per-mana-type skills modify elemAttune equivalent, or (b) rewrite computeElementMax to sum up per-type bonuses

Incomplete Implementation

3. Per-mana-type capacity upgrades (Bug 9) may not be integrated

   • Files: constants/skills.ts:8-21 (defines skills), but no code applies these to element max capacity
   • Need to verify: Whether the skills actually work or if they're just defined but never applied

4. essenceRefining skill has no effect (related to #1)

   • File: constants/skills.ts:35
   • Issue: Skill can be studied, but +10% enchantment effect power is never applied

Dead Code (Never Triggers)

5. enchantPower stat is defined but never read

   • 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 stat: 'enchantPower' but nothing reads it

6. elemAttune skill evolution path still exists but may be obsolete

   • File: skill-evolution.ts:1945- (SKILL_EVOLUTION_PATHS.elemAttune)
   • Issue: With per-mana-type skills (Bug 9), the generic elemAttune may be obsolete, but the evolution path still exists

---

Files Requiring Updates (Priority Order)

1. H1: Implement enchantPower in upgrade-effects.ts and effects.ts
2. H2: Fix computeElementMax in store.ts, utils/mana-utils.ts, store/computed.ts
3. H3: Verify unified effects usage in crafting-slice.ts
4. M1: Add special effects display to SkillsTab/StatsTab
5. M2: Display per-mana-type upgrades in UI
6. M3: Clean up elemAttune legacy references
7. M4: Add validation feedback for element mana costs

---

Notes

• The enchantPower issue is the most critical finding - it means the Essence Refining investigation (Bug 15) was partially correct in identifying issues, but the root cause is that enchantPower stat is never applied anywhere
• The per-mana-type capacity upgrades (Bug 9) need verification that they actually work - the skills are defined but may not be integrated into computeElementMax
• 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