diff --git a/docs/task3/effects_audit_report.md b/docs/task3/effects_audit_report.md new file mode 100644 index 0000000..d551b87 --- /dev/null +++ b/docs/task3/effects_audit_report.md @@ -0,0 +1,157 @@ +# 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 diff --git a/docs/task3/todo.md b/docs/task3/todo.md index 99ede08..493e8dc 100644 --- a/docs/task3/todo.md +++ b/docs/task3/todo.md @@ -26,7 +26,7 @@ - [x] Step 2: Sub-tasks planned and documented - [x] Step 3: Sub-tasks executed - [x] Step 4: UI Audit completed -- [ ] Step 5: Effects & Skills Audit completed +- [x] Step 5: Effects & Skills Audit completed ---