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 || 0` but should check individual per-mana-type skills (fireManaCap, waterManaCap, etc.) and apply their bonuses (+10% each level) to the respective element's max capacity | **NOT FIXED** |
| **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`
```typescript
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`
```typescript
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