Path of Exile 2 Build Optimizer MCP

# Resource Calculator Module ## Overview The `resource_calculator.py` module provides comprehensive resource calculations for Path of Exile 2, including the **new Spirit system** introduced in PoE2. **Location**: `C:\Users\tanki\ClaudesPathOfExile2EnhancementService\src\calculator\resource_calculator.py` ## What's NEW in Path of Exile 2 ### Spirit Resource System Spirit is a **brand new resource in PoE2** that wasn't present in PoE1. It serves as a limiting factor for: - **Permanent Minions**: Raise Zombie, Summon Skeleton, Summon Spectre, Golems - **Persistent Auras**: Some auras now reserve Spirit instead of mana - **Meta-Gems**: Special gems that provide ongoing effects This replaces the old mana reservation system for certain mechanics, providing better balance for minion builds and aura stackers. ### Formula Changes from PoE1 | Resource | PoE1 | PoE2 | Impact | |----------|------|------|--------| | **Life Base** | 38 + 12/level | **28 + 12/level** | -10 base life (characters start weaker) | | **Mana Scaling** | 34 + 6/level | **34 + 4/level** | Slower mana growth | | **Accuracy** | 2/level + 2/dex | **6/level + 6/dex** | 3× more accuracy (easier to hit) | | **Spirit** | N/A | **100 base + gear** | Completely new mechanic | ## Module Features ### Core Calculations - Maximum Life (PoE2 formula) - Maximum Mana (PoE2 formula) - Maximum Energy Shield - **Maximum Spirit (NEW)** - **Spirit Reservation Tracking (NEW)** - Mana Regeneration - Accuracy Rating - Attribute Bonuses ### Spirit System Features - Add/Remove Spirit reservations - Calculate total reserved Spirit - Check Spirit overflow (when over-reserved) - Toggle reservations on/off - Support gem multiplier calculations - Detailed reservation breakdown ### Utility Features - Resource pool management - Hit chance calculations - Comprehensive character summaries - Validation and error handling - Debug logging ## Quick Start ```python from calculator.resource_calculator import ( ResourceCalculator, AttributeStats, ResourceModifiers ) # Create character attributes = AttributeStats(strength=150, dexterity=100, intelligence=120) calc = ResourceCalculator(character_level=50, attributes=attributes) # Calculate resources max_life = calc.calculate_maximum_life() max_mana = calc.calculate_maximum_mana() max_spirit = calc.calculate_maximum_spirit() # Add Spirit reservations (NEW!) calc.add_spirit_reservation("Raise Zombie", base_cost=25, support_multipliers=[1.5]) calc.add_spirit_reservation("Summon Skeleton", base_cost=20, support_multipliers=[1.4, 1.3]) # Check Spirit status reserved = calc.calculate_spirit_reserved() available = calc.calculate_spirit_available(max_spirit) is_overflow, overflow_amt, _ = calc.check_spirit_overflow(max_spirit) if is_overflow: print(f"Warning: Over-reserved by {overflow_amt} Spirit!") ``` ## File Structure ``` src/calculator/ ├── resource_calculator.py # Main module (600+ lines) ├── RESOURCE_CALCULATOR_EXAMPLES.md # Detailed usage examples └── README_RESOURCE_CALCULATOR.md # This file tests/ └── test_resource_calculator.py # 44 unit tests (all passing) ``` ## Classes and Data Structures ### Core Classes - **`ResourceCalculator`**: Main calculator class - **`AttributeStats`**: Character attributes (Str/Dex/Int) - **`ResourceModifiers`**: Flat/Increased/More modifiers - **`SpiritReservation`**: Individual Spirit reservation (NEW) - **`ResourcePool`**: Resource pool with reservations ### Enumerations - **`ResourceType`**: LIFE, MANA, ENERGY_SHIELD, SPIRIT - **`ReservationType`**: MANA_FLAT, MANA_PERCENT, LIFE_FLAT, LIFE_PERCENT, SPIRIT_FLAT ## PoE2 Formulas Implemented ### Life (PoE2) ``` Base = 28 + (12 × level) + (2 × strength) + flat_bonuses Final = Base × (1 + increased%) × more_multipliers ``` ### Mana (PoE2) ``` Base = 34 + (4 × level) + (2 × intelligence) + flat_bonuses Final = Base × (1 + increased%) × more_multipliers Regen = 4% of max mana per second (base) ``` ### Spirit (NEW in PoE2) ``` Base = 100 (from quests) + flat_bonuses (from gear/passives) Final = Base × (1 + increased%) × more_multipliers Spirit_Cost = base_cost × support_multiplier_1 × support_multiplier_2 × ... Reserved = sum(all active Spirit costs) Available = Maximum - Reserved ``` ### Energy Shield ``` Base = flat_bonuses (no inherent base) Final = Base × (1 + increased%) × more_multipliers ``` ### Accuracy (PoE2) ``` Base = (6 × level) + (6 × dexterity) + flat_bonuses Final = Base × (1 + increased%) ``` ### Attribute Bonuses - **Strength**: +2 Life per point - **Dexterity**: +6 Accuracy per point - **Intelligence**: +2 Mana per point ## Testing The module includes comprehensive unit tests: ```bash # Run all tests python -m pytest tests/test_resource_calculator.py -v # Run with coverage python -m pytest tests/test_resource_calculator.py --cov=src.calculator.resource_calculator # Run specific test class python -m pytest tests/test_resource_calculator.py::TestResourceCalculator -v ``` **Test Coverage**: 44 tests covering: - Attribute validation - Resource calculations (Life, Mana, ES, Spirit) - Spirit reservation management - Resource pools - Hit chance calculations - Formula constants verification ## Usage Examples ### Basic Resource Calculation ```python calc = ResourceCalculator(level=70, attributes=AttributeStats(150, 100, 120)) life_mods = ResourceModifiers(flat_bonus=50, increased_percent=150) max_life = calc.calculate_maximum_life(life_mods) # Result: 28 + (12×70) + (2×150) + 50 = 1168 base # 1168 × 2.5 = 2920 final ``` ### Spirit Reservation Management ```python # Add minions with support gems calc.add_spirit_reservation("Raise Zombie", 25, [1.5]) # 38 Spirit calc.add_spirit_reservation("Skeleton Mage", 20, [1.4, 1.3]) # 37 Spirit calc.add_spirit_reservation("Stone Golem", 30, []) # 30 Spirit # Check status max_spirit = calc.calculate_maximum_spirit() # 100 base reserved = calc.calculate_spirit_reserved() # 105 available = calc.calculate_spirit_available(max_spirit) # -5 (overflow!) # Handle overflow if available < 0: print(f"Need {abs(available)} more Spirit!") calc.toggle_spirit_reservation("Stone Golem") # Disable golem available = calc.calculate_spirit_available(max_spirit) # 25 (OK!) ``` ### Complete Character Summary ```python summary = calc.calculate_all_resources( life_mods=life_mods, mana_mods=mana_mods, spirit_mods=spirit_mods ) print(f"Life: {summary['resources']['life']['maximum']}") print(f"Mana: {summary['resources']['mana']['maximum']}") print(f"Spirit: {summary['resources']['spirit']['available']}/{summary['resources']['spirit']['maximum']}") print(f"Accuracy: {summary['accuracy']['rating']}") ``` ## API Reference ### ResourceCalculator Methods #### Resource Calculations - `calculate_maximum_life(modifiers)` - Calculate max life - `calculate_maximum_mana(modifiers)` - Calculate max mana - `calculate_maximum_energy_shield(modifiers)` - Calculate max ES - `calculate_maximum_spirit(modifiers)` - Calculate max Spirit (NEW) - `calculate_mana_regeneration(max_mana, increased, flat)` - Calculate mana regen - `calculate_accuracy(flat, increased)` - Calculate accuracy rating #### Spirit Management (NEW) - `add_spirit_reservation(name, cost, multipliers)` - Add reservation - `remove_spirit_reservation(name)` - Remove reservation - `toggle_spirit_reservation(name)` - Toggle on/off - `calculate_spirit_reserved()` - Total reserved Spirit - `calculate_spirit_available(max)` - Available Spirit - `check_spirit_overflow(max)` - Check for overflow - `get_spirit_reservation_details()` - Detailed breakdown #### Utilities - `get_attribute_bonuses()` - Get all attribute bonuses - `create_resource_pool(type, mods)` - Create resource pool - `calculate_all_resources(mods...)` - Complete summary ### Helper Functions - `calculate_hit_chance(accuracy, evasion)` - Hit chance calculation ## Logging The module uses Python's `logging` module for debugging: ```python import logging # Enable debug logging logging.basicConfig(level=logging.DEBUG) # All calculations will now log details calc.calculate_maximum_life() # Logs: "Life calculation: base=828, increased%=0, final=828.0" ``` ## Constants All PoE2 formula constants are defined as class variables: ```python ResourceCalculator.BASE_LIFE_AT_LEVEL_1 = 28 ResourceCalculator.LIFE_PER_LEVEL = 12 ResourceCalculator.LIFE_PER_STRENGTH = 2 ResourceCalculator.BASE_MANA_AT_LEVEL_1 = 34 ResourceCalculator.MANA_PER_LEVEL = 4 ResourceCalculator.MANA_PER_INTELLIGENCE = 2 ResourceCalculator.BASE_SPIRIT_FROM_QUESTS = 100 # NEW ResourceCalculator.ACCURACY_PER_LEVEL = 6 ResourceCalculator.ACCURACY_PER_DEXTERITY = 6 ``` ## Error Handling The module validates inputs and raises appropriate errors: ```python # Invalid level ResourceCalculator(level=0, attributes=attrs) # ValueError # Negative attributes AttributeStats(strength=-10, dex=50, int=50) # ValueError # Unsupported resource type calc.create_resource_pool(ResourceType.INVALID) # ValueError ``` ## Performance - All calculations: **O(1)** complexity - Spirit reservations: **O(n)** where n = number of reservations - Typical use case: **< 1ms** per calculation - Batch calculations recommended for multiple resources ## Integration This module integrates with: - **Build Planner**: Character resource planning - **Damage Calculator**: Accuracy/hit chance calculations - **Defense Calculator**: Life/ES/Evasion integration - **Gem Manager**: Spirit cost tracking ## Documentation - **This README**: Overview and quick reference - **RESOURCE_CALCULATOR_EXAMPLES.md**: Detailed examples and use cases - **Inline docstrings**: Full API documentation in code - **Unit tests**: 44 tests demonstrating usage ## Spirit System Deep Dive ### Why Spirit Exists (PoE2 Design) In Path of Exile 1, mana reservation was used for auras, which led to: 1. Aura stackers being too powerful 2. Minion builds having no limitation 3. Balance issues with "reservation efficiency" Path of Exile 2 introduces **Spirit** as a separate resource to: 1. **Limit minion builds** - Can't summon unlimited minions 2. **Balance auras** - Some auras use Spirit instead of mana 3. **Create build choices** - Force players to choose which buffs to run 4. **Prevent stacking** - Spirit is much harder to scale than mana reservation ### How to Get Spirit 1. **Quest Rewards**: Base 100 Spirit (similar to skill points) 2. **Gear Affixes**: "+15 to Maximum Spirit" on items 3. **Passive Tree**: Spirit nodes (rare) 4. **Increased Spirit**: "10% increased Maximum Spirit" (very rare) ### Spirit vs Mana Reservation | Feature | Spirit | Mana Reservation | |---------|--------|------------------| | Base amount | 100 (fixed) | Scales with level/Int | | Scaling | Very limited | Easy to scale | | Used for | Minions, some auras | Most auras, heralds | | Calculation | Flat costs | % or flat | | Supports affect cost | Yes (multiplicative) | Yes (multiplicative) | | Can be unreserved | Yes | Yes | ### Common Spirit Costs *Note: These are example costs; actual values may differ in PoE2* **Minions**: - Raise Zombie: 20-30 Spirit - Summon Skeleton: 15-25 Spirit - Summon Raging Spirit: 10-20 Spirit (temporary, might not cost Spirit) - Summon Golem: 25-35 Spirit - Summon Spectre: 30-40 Spirit **Auras** (Spirit-based): - Some defensive auras: 20-35 Spirit - Some offensive auras: 25-40 Spirit - Meta-gems: 15-30 Spirit ### Support Gem Multipliers Support gems increase Spirit costs just like mana multipliers: ```python # Example: Zombie with 2 supports base_cost = 25 supports = [1.3, 1.4] # Minion Damage, Minion Life final_cost = 25 × 1.3 × 1.4 = 45.5 → 46 Spirit (rounded up) ``` Common support multipliers: - Damage supports: 1.3× - Life supports: 1.4× - Speed supports: 1.25× - Special supports: 1.5×+ ### Build Planning with Spirit ```python # Calculate Spirit budget for a necromancer build max_spirit = 180 # 100 base + 80 from gear # Plan minions zombies = 25 × 1.5 = 38 Spirit (with support) skeletons = 20 × 1.4 = 28 Spirit (with support) golem = 30 Spirit (no support) spectres = 35 × 1.5 = 53 Spirit (with support) total = 38 + 28 + 30 + 53 = 149 Spirit remaining = 180 - 149 = 31 Spirit # Room for 1 more small minion or aura ``` ## Version History - **v1.0** (2025-10-22): Initial release with full PoE2 support including Spirit system ## Author Created by Claude for Path of Exile 2 Enhancement Service ## License Part of ClaudesPathOfExile2EnhancementService project