path: root/README.md

# Genshin Impact Artifact Optimizer

An automated artifact optimization system based on the scoring methodology by Sevy. This tool helps you find the best artifact builds for multiple characters by intelligently distributing your artifact inventory based on priority order.

## 🎯 Features

- **Character Priority System**: Assign artifacts to characters in your specified priority order
- **Intelligent Scoring**: Uses the proven scoring system that accounts for all relevant substats
- **Energy Recharge Compliance**: Automatically checks if builds meet ER requirements  
- **Flexible Main Stats**: Supports character-specific ideal main stat preferences
- **4-Star Fallback**: Uses 4-star artifacts when suitable 5-star pieces aren't available
- **Interactive Interface**: Easy-to-use command-line interface for character selection
- **Detailed Reporting**: Comprehensive build analysis with scores and recommendations

## 📊 Scoring Methodology

Based on the artifact scoring system that converts substat rolls into a 0-100 score:

### Special Numbers (Stat Weights)
- **CRIT Rate**: 3.0
- **CRIT DMG**: 6.0  
- **ATK%**: 5.0
- **HP%**: 5.0
- **DEF%**: 6.0
- **Energy Recharge**: 5.5
- **Elemental Mastery**: 20.0
- **Flat ATK**: 45.0
- **Flat HP**: 700.0
- **Flat DEF**: 50.0

### Score Calculation
For each artifact:
1. Divide each relevant substat value by its special number
2. Sum all the values (represents substat roll count)
3. Divide by 9 (max possible rolls) and multiply by 100

### Quality Tiers
- **44+ Good**: Can clear Abyss with difficulty
- **55+ Great**: Comfortable Abyss clearing
- **66+ Amazing**: Well-built character, strong performance
- **77+ Insane**: Excellent builds, Abyss feels easy
- **88+ God-like**: Exceptional builds, lottery-winner luck
- **99+ Exodia**: Theoretical perfection

## 🚀 Quick Start

### Prerequisites
- Python 3.6+
- Genshin Impact artifact data (JSON format)

### Basic Usage

1. **Automated Mode** (uses predefined character priority):
```bash
python artifact_optimizer.py
```

2. **Interactive Mode** (select your own characters):
```bash
python interactive_optimizer.py
```

### Data Files Required

**data.json** - Your artifact inventory in the format:
```json
{
  "format": "GOOD",
  "version": 2,
  "artifacts": [
    {
      "setKey": "GoldenTroupe",
      "slotKey": "flower",
      "rarity": 5,
      "mainStatKey": "hp",
      "level": 20,
      "substats": [
        {"key": "critRate_", "value": 10.1},
        {"key": "critDMG_", "value": 14.0},
        {"key": "hp_", "value": 16.9},
        {"key": "enerRech_", "value": 11.7}
      ],
      "id": 1
    }
  ]
}
```

**characters.json** - Character build requirements:
```json
{
  "Furina": {
    "er_requirement": {"min": 180, "max": 200},
    "ideal_main_stats": {
      "sands": ["HP%", "ER%"],
      "goblet": ["HP%", "Hydro DMG Bonus"],
      "circlet": ["CRIT Rate", "CRIT DMG"]
    },
    "substat_priority": ["ER%", "CRIT Rate", "CRIT DMG", "HP%", "Flat HP"]
  }
}
```

## 🎮 Interactive Mode Features

### Character Selection
- View all available characters
- Add characters to priority list in any order
- Remove characters from priority list
- View detailed character requirements

### Character Information Display
- Energy Recharge requirements
- Ideal main stats for each artifact slot
- Substat priority ranking
- Special notes and considerations

### Optimization Settings
- Enable/disable 4-star fallback artifacts
- Adjust ER requirement flexibility
- Customize scoring parameters

## 📋 Example Output

```
==================== FURINA ====================
📊 Average Artifact Score: 59.46/100
✅ Energy Recharge: 180.3% (180-200%)

📋 ARTIFACT BUILD:

Flower (GoldenTroupe) - Level 16 ⭐⭐⭐⭐⭐
  Main Stat: hp
  Score: 87.12/100
  Substats:
    • critDMG_: 14.0%
    • hp_: 16.9%
    • enerRech_: 11.7%
    • critRate_: 6.2%
```

## 🔧 How It Works

### Priority-Based Assignment
1. Characters are processed in your specified priority order
2. For each character, the system finds the best possible 5-piece build
3. Once artifacts are assigned, they're removed from the pool
4. Later characters get the best remaining artifacts

### Smart Main Stat Filtering
- Only considers artifacts with suitable main stats for each character
- Falls back to 4-star artifacts if no suitable 5-star pieces exist
- Respects character-specific requirements (e.g., Chiori needs DEF%)

### Energy Recharge Validation
- Calculates total ER from main stats and substats  
- Supports complex ER requirements (multiple scenarios)
- Provides flexibility buffer for realistic builds

### Build Quality Assessment
- Scores each individual artifact for the specific character
- Averages scores across all 5 pieces
- Adjusts scores based on ER requirement compliance

## 📁 File Structure

```
test/
├── artifact_optimizer.py      # Core optimization engine
├── interactive_optimizer.py   # Interactive user interface
├── data.json                 # Your artifact inventory
├── characters.json           # Character requirements
├── README.md                 # This file
└── optimization_results.txt  # Generated results
```

## 🎯 Supported Characters

Currently includes optimized builds for:
- **Furina**: HP/Hydro DPS hybrid
- **Escoffier**: Cryo DPS  
- **Fischl**: Electro off-field DPS
- **Chiori**: Geo DEF-scaling DPS

Add more characters by extending the `characters.json` file.

## 💡 Tips for Best Results

1. **Prioritize wisely**: Put your most important characters first
2. **Include ER requirements**: Builds that can't rotate are useless
3. **Don't over-optimize**: 66+ scores are excellent for most content
4. **Consider set bonuses**: The optimizer focuses on substats, manually verify set effects
5. **Level your artifacts**: Higher level = better main stats = higher scores

## 🔮 Future Enhancements

- Set bonus consideration in scoring
- Weapon-specific optimizations  
- Team composition analysis
- GUI interface
- Database integration
- Cloud save support

## 📖 Credits

- Scoring methodology inspired by Sevy's artifact rating system
- Built for the Genshin Impact theorycrafting community
- Special thanks to all TCers who contribute to character guides

## 🐛 Troubleshooting

**"No suitable build found"**: Character needs specific main stats not available in your inventory

**Low scores across all builds**: Your artifact quality may need improvement through farming

**ER requirements not met**: Consider ER% sands or prioritize ER substats

**Missing character data**: Add character requirements to `characters.json`

---

*Happy artifact farming, Traveler! May your rolls be blessed by RNGesus.* 🎲✨