Mana-Loop/docs/context-mana-conversion-fix.md

Context: Mana Conversion Attunement Fix

Problem Statement

Mana conversion from attunements (e.g., Enchanter Transference mana) incorrectly deducts mana from the player's mana pool every tick instead of reducing raw mana regen. This causes players to get stuck at 1 mana below their mana cap.

Required Fix

Modify attunement mana conversion logic to:

1. Calculate conversion costs as a reduction to raw mana regen (not a direct deduction from mana pool)
2. Ensure the deduction is applied before mana regen calculations
3. Prevent mana pool from being stuck below cap due to continuous deductions

Key Files to Investigate/Modify

• src/lib/game/attunements/ - Attunement definitions and logic
• src/lib/game/stores/manaStore.ts - Mana state and regen calculations
• src/lib/game/stores/gameLoopActions.ts - Game tick logic
• src/lib/game/stores/gameStore.ts - Core tick processing
• src/lib/game/upgrade-effects.ts - Effect calculations

Architecture Rules (from AGENTS.md)

• Use modular stores in src/lib/game/stores/ - NEVER use legacy store.ts pattern
• All files must stay under 400 lines (pre-commit hook enforced)
• No banned content (lifesteal, healing, banned mana types: life, blood, wood, mental, force)
• Use unified effect system (effects.ts) for stat modifications

Relevant Code References

• Attunement transference cost calculation
• computeRegen() function in computed-stats.ts
• Mana pool cap logic in manaStore.ts
• Game tick loop that processes attunement effects

Expected Outcome

• Mana conversion costs reduce raw mana regen rate instead of deducting from mana pool
• Players no longer get stuck below mana cap
• Regression test added to src/lib/game/stores/__tests__/mana-store-tests/