# EU-Utility User Manual

> Complete guide for using EU-Utility - Your Entropia Universe companion
> 
> **Version:** 2.0  
> **Last Updated:** 2025-02-14

---

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Getting Started](#getting-started)
4. [Global Hotkeys](#global-hotkeys)
5. [Plugins Overview](#plugins-overview)
6. [Using Each Plugin](#using-each-plugin)
7. [Dashboard](#dashboard)
8. [Settings](#settings)
9. [Tips & Tricks](#tips--tricks)

---

## Introduction

**EU-Utility** is a versatile overlay utility for Entropia Universe players. It provides quick access to calculators, trackers, and tools without leaving the game.

### Key Features

- 🎮 **Global Hotkey Overlay** - Access tools with keyboard shortcuts
- 🔍 **Universal Search** - Search Entropia Nexus for items, mobs, locations
- 🧮 **Calculators** - DPP, crafting, enhancer calculations
- 📊 **Trackers** - Loot, skills, missions, codex progress
- 🎵 **Spotify Control** - Control music without alt-tabbing
- 🔌 **Plugin System** - Extend with custom plugins

---

## Installation

### Requirements

- **Windows 10/11** (primary support)
- **Linux** (limited support)
- **Python 3.11+**
- **Entropia Universe** (optional, for game integration)

### Step 1: Install Python

Download and install Python 3.11 or newer from [python.org](https://python.org)

**Important:** Check "Add Python to PATH" during installation.

### Step 2: Download EU-Utility

```bash
# Clone or download the repository
git clone <repository-url>
cd EU-Utility
```

### Step 3: Install Dependencies

```bash
pip install -r requirements.txt
```

### Step 4: Run EU-Utility

```bash
python -m core.main
```

---

## Getting Started

### First Launch

When you start EU-Utility for the first time:

1. **Floating Icon Appears** - A small icon appears on your screen
2. **Double-click** to open the main overlay
3. **Use hotkeys** for quick access (see below)

### The Floating Icon

![Floating Icon](assets/floating_icon.png)

- **Double-click**: Toggle main overlay
- **Right-click**: Context menu
- **Drag**: Move to preferred position

### Main Overlay

The overlay is a semi-transparent window that stays on top of other windows. It contains:

- **Plugin tabs** on the left
- **Plugin content** in the center
- **Quick actions** at the bottom

---

## Global Hotkeys

Hotkeys work even when EU-Utility is hidden:

| Hotkey | Action |
|--------|--------|
| `Ctrl + Shift + U` | Toggle main overlay |
| `Ctrl + Shift + H` | Hide all overlays |
| `Ctrl + Shift + F` | Universal Search |
| `Ctrl + Shift + C` | Calculator |
| `Ctrl + Shift + M` | Spotify Controller |
| `Ctrl + Shift + R` | Game Reader (OCR) |
| `Ctrl + Shift + S` | Skill Scanner |
| `Ctrl + Shift + D` | DPP Calculator |
| `Ctrl + Shift + L` | Loot Tracker |
| `Ctrl + Shift + N` | Nexus Search |
| `Ctrl + Shift + E` | Enhancer Calculator |
| `Ctrl + Shift + B` | Crafting Calculator |
| `Ctrl + Shift + X` | Codex Tracker |
| `Ctrl + Shift + ,` | Settings |
| `Ctrl + Shift + Home` | Dashboard |

### Customizing Hotkeys

1. Open **Settings** plugin (`Ctrl + Shift + ,`)
2. Click the **Hotkeys** tab
3. Edit the hotkey combinations
4. Click **Save Settings**

---

## Plugins Overview

EU-Utility comes with **21 built-in plugins**:

### Utility Plugins

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **Dashboard** | Overview of your avatar stats | `Ctrl+Shift+Home` |
| **Calculator** | Standard calculator | `Ctrl+Shift+C` |
| **Settings** | Configure EU-Utility | `Ctrl+Shift+,` |

### Search Plugins

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **Universal Search** | Search all Nexus entities | `Ctrl+Shift+F` |
| **Nexus Search** | Search items and market | `Ctrl+Shift+N` |

### Calculator Plugins

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **DPP Calculator** | Damage Per PEC calculator | `Ctrl+Shift+D` |
| **Crafting Calc** | Blueprint calculator | `Ctrl+Shift+B` |
| **Enhancer Calc** | Enhancer break rates | `Ctrl+Shift+E` |

### Tracker Plugins

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **Loot Tracker** | Track hunting loot & ROI | `Ctrl+Shift+L` |
| **Skill Scanner** | Track skill gains | `Ctrl+Shift+S` |
| **Mission Tracker** | Track missions & challenges | - |
| **Codex Tracker** | Track creature challenges | `Ctrl+Shift+X` |
| **Mining Helper** | Track mining claims | - |
| **Auction Tracker** | Track auction listings | - |
| **Inventory Manager** | Manage inventory | - |
| **Global Tracker** | Track globals & HOFs | - |

### Game Integration

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **Game Reader** | OCR for game menus | `Ctrl+Shift+R` |
| **Chat Logger** | Log chat messages | - |

### External Integration

| Plugin | Purpose | Hotkey |
|--------|---------|--------|
| **Spotify Controller** | Control Spotify | `Ctrl+Shift+M` |

---

## Using Each Plugin

### Dashboard

Your personal command center showing:

- **PED Balance** - Total TT value of inventory
- **Skills Tracked** - Number of skills being monitored
- **Inventory Items** - Item count
- **Today's Skill Gains** - Gains in the last 24 hours
- **Session Time** - How long you've been playing

**Customizing the Dashboard:**

1. Click **Customize** button
2. Check/uncheck widgets to display
3. Click **Save**

### Universal Search

Search across all Entropia Nexus entities:

1. Press `Ctrl + Shift + F`
2. Select search mode (Universal or specific type)
3. Enter search term (e.g., "ArMatrix", "Atrox")
4. Press Enter or click Search
5. Double-click result to open on Nexus website

**Supported Entity Types:**
- Items, Weapons, Armors
- Mobs, Pets
- Blueprints, Materials
- Locations, Teleporters, Shops
- Skills
- And more...

### DPP Calculator

Calculate Damage Per PEC for your weapon setup:

1. Enter **Weapon Damage**
2. Enter **Ammo per shot**
3. Enter **Decay** (in PEC)
4. (Optional) Enter **Amp decay**
5. Click **Calculate**

**Understanding DPP:**
- **4.0+** = Excellent (95-100% efficiency)
- **3.5-4.0** = Very Good (85-95%)
- **3.0-3.5** = Good (75-85%)
- **2.5-3.0** = Average (60-75%)
- **< 2.5** = Poor (< 60%)

### Loot Tracker

Track your hunting sessions:

1. Click **Start Session** before hunting
2. Hunt normally
3. Click **Stop Session** when done
4. View statistics (kills, TT value, ROI)

**Features:**
- Automatic loot detection from chat
- Session history saved to disk
- ROI calculation

### Skill Scanner

Track your skill progress:

1. Open your Skills window in-game
2. Press `Ctrl + Shift + S`
3. Click **Scan Skills Window**
4. View scanned skills

**Features:**
- OCR-based skill reading
- Tracks skill gains over time
- Shows progress toward next level

### Spotify Controller

Control Spotify without leaving the game:

1. Press `Ctrl + Shift + M`
2. Use play/pause, next, previous buttons
3. Adjust volume with slider

**Requirements:**
- Spotify must be running
- On Linux: `playerctl` must be installed

### Game Reader (OCR)

Read text from in-game menus:

1. Open any menu in Entropia Universe
2. Press `Ctrl + Shift + R`
3. Click **Capture Screen**
4. View captured text
5. Click **Copy Text** to copy to clipboard

**Common Uses:**
- Read NPC dialogue
- Capture mission text
- Extract item stats
- Read shop prices

### Crafting Calculator

Calculate crafting costs:

1. Select **Blueprint Category**
2. Select **Blueprint**
3. Enter your **QR** (Quality Rating)
4. Enter number of **Clicks**
5. Click **Calculate**

Shows expected success rate and material costs.

### Enhancer Calculator

Calculate enhancer costs:

1. Select **Enhancer Type**
2. Enter **TT Value**
3. Enter **Shots per hour**
4. Click **Calculate**

Shows expected break rate and hourly cost.

### Mission Tracker

Track your missions:

- View active missions
- Track progress with progress bars
- Add new missions manually
- Mark missions complete

### Codex Tracker

Track creature codex progress:

- View all tracked creatures
- See current rank and progress
- Get estimated kills to next rank
- Scan codex window with OCR

### Mining Helper

Track mining activities:

- Add claims manually
- Track hit rate
- View recent claims
- Estimate TT values

---

## Dashboard

The Dashboard is your home screen in EU-Utility.

### Available Widgets

| Widget | Description |
|--------|-------------|
| PED Balance | Total TT value from inventory |
| Skills Tracked | Number of skills monitored |
| Inventory Items | Total item count |
| Current DPP | Last calculated DPP |
| Today's Skill Gains | Gains in last 24h |
| Professions Count | Tracked professions |
| Active Missions | Current mission count |
| Codex Progress | Creatures tracked |
| Globals/HOFs | Today's globals |
| Session Time | Play time today |

### Customizing

1. Click **Customize** button
2. Check widgets you want to see
3. Uncheck widgets to hide
4. Click **Save**

---

## Settings

Configure EU-Utility to your preferences.

### General Settings

**Appearance:**
- Theme (Dark/Light)
- Overlay opacity (50-100%)
- Icon size

**Behavior:**
- Start with Windows
- Minimize to tray
- Show tooltips

### Plugin Management

Enable or disable plugins:

1. Go to **Plugins** tab
2. Check/uncheck plugins
3. Changes apply immediately

### Hotkeys

Customize global hotkeys:

1. Go to **Hotkeys** tab
2. Click on a hotkey field
3. Press your desired key combination
4. Click **Save Settings**

### Data Management

**Export Data:**
- Creates backup of all your data
- Saves as JSON file

**Import Data:**
- Restore from backup
- Merges with existing data

**Clear Data:**
- Removes all saved data
- Cannot be undone

---

## Tips & Tricks

### Performance Tips

1. **Disable unused plugins** - Reduces memory usage
2. **Lower overlay opacity** - Less GPU usage
3. **Close unused overlay widgets** - Frees up resources

### Workflow Tips

1. **Use hotkeys** - Much faster than clicking
2. **Pin frequently used plugins** - Add to dashboard
3. **Keep Spotify open** - Controller works better
4. **Position floating icon** - Put where it won't interfere

### Troubleshooting

**Overlay not showing:**
- Press `Ctrl + Shift + U`
- Check if EU-Utility is running
- Try double-clicking floating icon

**Hotkeys not working:**
- Check if another app uses the same hotkey
- Try changing hotkey in Settings
- Run as Administrator (Windows)

**OCR not working:**
- Install EasyOCR: `pip install easyocr`
- Ensure game window is visible
- Try increasing brightness

**Spotify not detected:**
- Ensure Spotify is running
- On Linux: install `playerctl`
- Try restarting Spotify

---

## Getting Help

### Resources

- **Documentation**: See `docs/` folder
- **Plugin Development**: See `docs/PLUGIN_DEVELOPMENT.md`
- **API Reference**: See `docs/NEXUS_API_REFERENCE.md`

### Reporting Issues

1. Check existing documentation
2. Try restarting EU-Utility
3. Check the logs in `data/logs/`
4. Report with:
   - What you were doing
   - What you expected
   - What actually happened
   - Error messages

---

**Enjoy your time in Entropia Universe!** 🚀