# Lemontropia Suite — Windows PC Testing Guide

**Version:** v0.1.0-alpha  
**Platform:** Windows 10/11  
**Status:** Ready for Live Game Testing

---

## 🎯 What This Tool Does

**Lemontropia Suite** is a professional analytics platform for **Entropia Universe** players. It tracks your hunting, mining, and crafting activities with precision.

### Core Capabilities

| Feature | Description | Benefit |
|---------|-------------|---------|
| **Real-Time Loot Tracking** | Parses `chat.log` live | Instant ROI calculation |
| **Global/HoF Detection** | Auto-screenshot on >50 PED | Never miss big wins |
| **Skill Gain Logging** | Tracks all skill advances | Progress monitoring |
| **Weapon Decay Calc** | Precise PEC tracking | True cost analysis |
| **Project Management** | Hunt/Mine/Craft projects | Organized data |
| **Session Analytics** | Per-session ROI & profit | Performance metrics |
| **Gear Integration** | Entropia Nexus API | Automatic weapon stats |

---

## 📋 TERMINOLOGY (Important!)

Understanding the data model:

```
PROJECT (Activity Definition)
├── "Daily Argo Grind" (Hunting project)
│   ├── SESSION 1: Morning hunt (45 min, +15 PED)
│   ├── SESSION 2: Evening hunt (2 hrs, -5 PED)
│   └── SESSION 3: Weekend marathon (5 hrs, +200 PED)
│
└── Combined stats: Total sessions, average ROI, lifetime profit
```

| Term | Definition | Example |
|------|------------|---------|
| **PROJECT** | Long-term activity container | "Argo Hunting", "Calypso Mining" |
| **SESSION** | Single gameplay instance | One hunting trip |
| **RUN** | Complete project lifecycle | Multiple sessions over days |

---

## 🚀 Windows Setup Instructions

### Step 1: Install Python

1. Download Python 3.11+ from [python.org](https://www.python.org/downloads/)
2. **IMPORTANT:** Check "Add Python to PATH" during installation
3. Verify: Open Command Prompt (`cmd`) and run:
   ```cmd
   python --version
   ```

### Step 2: Clone/Download the Project

Option A: Git (if you have it installed)
```cmd
git clone https://git.lemonlink.eu/impulsivefps/Lemontropia-Suite.git
cd Lemontropia-Suite
```

Option B: Download ZIP
1. Go to: `https://git.lemonlink.eu/impulsivefps/Lemontropia-Suite`
2. Click "Download ZIP"
3. Extract to `C:\Lemontropia-Suite\`
4. Open Command Prompt in that folder

### Step 3: Configure Environment

Create `.env` file in the project folder:

```env
# Windows paths use double backslashes
EU_CHAT_LOG_PATH=C:\\Users\\ImpulsiveFPS\\Documents\\Entropia Universe\\chat.log

# For mock testing (no game needed)
USE_MOCK_DATA=false

# Obsidian integration (optional)
OBSIDIAN_API_URL=http://192.168.5.30:27123
OBSIDIAN_API_KEY=your_key_here

# Enable debug output
LOG_LEVEL=info
```

**Find your actual log path:**
```
C:\Users\[YourUsername]\Documents\Entropia Universe\chat.log
```

### Step 4: Run the Application

```cmd
python main.py
```

---

## 🎮 Testing Scenarios

### Test 1: Live Hunt Tracking (With Game Running)

**Prerequisites:**
- Entropia Universe game running
- Character in a safe hunting zone
- Weapon equipped

**Steps:**
1. Start Lemontropia Suite: `python main.py`
2. Select `1` → Create New Project
3. Name: `Test Hunt` → Type: `1` (Hunting)
4. Select `3` → Start New Session
5. Choose your `Test Hunt` project
6. **In game:** Shoot a creature once
7. **Expected:** Lemontropia shows decay/ammo cost
8. **In game:** Kill creature, loot
9. **Expected:** Lemontropia shows loot items + TT value
10. Press `Ctrl+C` to end session
11. Select `4` → View Statistics → See ROI

**Success Criteria:**
- [ ] Decay recorded correctly
- [ ] Loot items captured
- [ ] TT values accurate
- [ ] ROI calculation reasonable

---

### Test 2: Global Detection

**Steps:**
1. Start a new session
2. **In game:** Type `/global` in chat (simulated) OR wait for real global
3. **Expected:** Lemontropia shows:
   ```
   🌍 GLOBAL: PlayerName found 150.00 PED!
   ```
4. Check `screenshots/` folder for auto-capture

---

### Test 3: Skill Gain Tracking

**Steps:**
1. Start a new session
2. **In game:** Hunt until skill gain message appears
3. **Expected:** Lemontropia shows:
   ```
   📈 Skill: Rifle +0.45
   ```

---

### Test 4: Multi-Session Project

**Steps:**
1. Create project: `Argo Grind Week 1`
2. Start Session 1 → Hunt 10 minutes → End
3. Start Session 2 → Hunt 10 minutes → End
4. Start Session 3 → Hunt 10 minutes → End
5. View statistics → Should show:
   - 3 sessions total
   - Combined profit/loss
   - Average ROI across all sessions

---

### Test 5: Gear Loadout (Entropia Nexus Integration)

**Steps:**
1. In Lemontropia menu, select gear management (when implemented)
2. Search for your weapon: `Omegaton M2100`
3. **Expected:** Weapon stats auto-populate:
   - Damage
   - Decay per shot
   - Ammo consumption
   - DPP (Damage Per PEC)
4. Calculate cost per hour estimate

---

## 🔍 Troubleshooting

### Issue: "chat.log not found"
**Solution:**
1. Verify EU is running and you've logged in at least once
2. Check path in `.env` matches your Windows username
3. Try running as Administrator (permissions issue)

### Issue: "Database error"
**Solution:**
```cmd
# Delete database and reinitialize
del data\lemontropia.db
python main.py
```

### Issue: "No events detected"
**Solution:**
1. Verify `USE_MOCK_DATA=false` in `.env`
2. Check that EU client is writing to chat.log (open it in Notepad, should show recent entries)
3. Ensure no other log-reading tools are locking the file

### Issue: "Permission denied"
**Solution:**
Run Command Prompt as Administrator

---

## 📊 Expected Log Format

Your `chat.log` should contain lines like:

```
2026-02-08 14:23:15 [System] You received Shrapnel x 50 (Value: 0.50 PED)
2026-02-08 14:23:45 [System] You gained 0.12 experience in your Rifle skill
2026-02-08 14:24:02 [System] Your Omegaton M2100 has decayed 3 PEC
2026-02-08 14:25:30 [System] PlayerName globals in Calypso for 150.00 PED
2026-02-08 14:26:10 [System] You killed a Argo Young
```

---

## 🛠️ Development Features (In Progress)

### Coming Soon

| Feature | Status | Description |
|---------|--------|-------------|
| Gear Loadout Manager | 🚧 WIP | Select weapons, get stats from Nexus |
| Live HUD Overlay | 📋 Planned | Transparent always-on-top window |
| Mining Map | 📋 Planned | Coordinate tracking + heat maps |
| Crafting Calculator | 📋 Planned | BP success rate + residue calc |
| Auto-Screenshot | ✅ Ready | Triggers on >50 PED |
| Data Export | 📋 Planned | CSV/Excel export |

---

## 📈 ROI Calculation Explained

**Formula:**
```
ROI% = (Total Loot TT / Total Cost) × 100
```

**Total Cost includes:**
- Weapon decay (PEC)
- Ammo consumed (PEC)
- Armor decay (PEC)
- Healing costs (if tracked)
- Enhancer breaks (if tracked)

**Example:**
```
Session: 1 hour hunting
- Cost: 50 PED (ammo + decay)
- Loot: 45 PED TT value
- ROI: (45 / 50) × 100 = 90% (10% loss)
```

---

## 🔐 Security Notes

- Tool only **READS** from `chat.log` (never writes)
- Tool does NOT interact with game memory
- Tool does NOT automate gameplay
- All data stored locally in SQLite database
- No internet connection required (except Nexus API lookups)

---

## 📞 Support

**Repository:** https://git.lemonlink.eu/impulsivefps/Lemontropia-Suite

**Issue Reporting:**
1. What test were you running?
2. What did you expect to happen?
3. What actually happened?
4. Screenshot of error (if any)

---

*Happy Hunting! 🍋*