# EU-Utility User Guide

## Table of Contents

1. [Getting Started](#getting-started)
2. [Installation](#installation)
3. [First Launch](#first-launch)
4. [Main Interface](#main-interface)
5. [Plugins](#plugins)
6. [Hotkeys](#hotkeys)
7. [Settings](#settings)
8. [Tips & Tricks](#tips--tricks)
9. [FAQ](#faq)

---

## Getting Started

Welcome to EU-Utility! This guide will help you get up and running quickly.

### What is EU-Utility?

EU-Utility is a powerful overlay utility designed specifically for Entropia Universe players. It provides:

- Quick access to calculators and trackers
- Real-time game data integration
- Customizable hotkeys for instant access
- Modular plugin system for extensibility

---

## Installation

### System Requirements

- **OS:** Windows 10/11 (full support) or Linux (limited support)
- **Python:** 3.11 or higher
- **Memory:** 4GB RAM minimum
- **Storage:** 100MB free space

### Step-by-Step Installation

1. **Download the application:**
   ```bash
   git clone https://github.com/ImpulsiveFPS/EU-Utility.git
   cd EU-Utility
   ```

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Verify installation:**
   ```bash
   python -m pytest tests/unit/ -v
   ```

### Optional Dependencies

For OCR (text recognition) features:

```bash
# Recommended - Auto-installs
pip install easyocr

# OR Tesseract (alternative)
pip install pytesseract

# OR PaddleOCR (advanced)
pip install paddleocr
```

---

## First Launch

### Starting EU-Utility

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

### What You'll See

1. **Floating Icon** - A small icon appears on your screen
2. **System Tray** - EU-Utility icon appears in your system tray
3. **Initial Setup** - First-time configuration wizard (if applicable)

### The Floating Icon

| Action | Result |
|--------|--------|
| **Double-click** | Open main overlay |
| **Right-click** | Context menu |
| **Drag** | Move to preferred position |

---

## Main Interface

### Overlay Window

The main overlay consists of:

```
┌─────────────────────────────────────────────────────┐
│  EU-Utility v2.0                          [_][X]   │
├──────────┬──────────────────────────────────────────┤
│          │                                          │
│ Plugins  │                                          │
│          │         Plugin Content Area              │
│ • Search │                                          │
│ • Calc   │                                          │
│ • Track  │                                          │
│ • ...    │                                          │
│          │                                          │
├──────────┴──────────────────────────────────────────┤
│  [Theme] [Settings]                              │
└─────────────────────────────────────────────────────┘
```

### Navigation

- **Sidebar:** Click plugin names to switch
- **Keyboard:** Press `Ctrl+1` through `Ctrl+9` to switch plugins
- **Search:** Use the search box for quick plugin access

---

## Plugins

### Built-in Plugins

#### Search & Information
- **Universal Search** - Search all Nexus entities
- **Nexus Search** - Item and market data search

#### Calculators
- **DPP Calculator** - Damage Per PEC calculation
- **Crafting Calculator** - Blueprint success rates
- **Enhancer Calculator** - Break rate analysis

#### Trackers
- **Loot Tracker** - Hunting loot tracking
- **Skill Scanner** - Skill gain monitoring
- **Codex Tracker** - Creature challenge progress

#### Game Integration
- **Game Reader** - OCR for in-game text
- **Chat Logger** - Chat log analysis

### Enabling/Disabling Plugins

1. Open Settings (`Ctrl+Shift+,`)
2. Go to "Plugins" tab
3. Check/uncheck plugins to enable/disable
4. Click "Save Changes"

### Installing New Plugins

1. Open Settings
2. Go to "Plugin Store" tab
3. Browse available plugins
4. Click "Install" on desired plugin
5. Restart EU-Utility if required

---

## Hotkeys

### Default Hotkeys

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

### Customizing Hotkeys

1. Open Settings
2. Go to "Hotkeys" tab
3. Click on the action you want to change
4. Press your desired key combination
5. Click "Save Changes"

---

## Settings

### General Settings

**Appearance:**
- Theme (Dark/Light)
- Overlay opacity
- Font size

**Behavior:**
- Auto-hide delay
- Startup with Windows
- Minimize to tray

**Notifications:**
- Enable/disable notifications
- Sound alerts
- Notification duration

### Plugin Settings

Each plugin may have its own settings:

1. Select the plugin in the sidebar
2. Look for a settings icon (⚙️) or menu
3. Adjust settings as needed

### Advanced Settings

Edit `config/settings.json` directly for advanced options:

```json
{
  "hotkeys": {
    "toggle": "ctrl+shift+u"
  },
  "theme": {
    "mode": "dark",
    "opacity": 0.95
  },
  "overlay": {
    "always_on_top": true,
    "remember_position": true
  }
}
```

---

## Tips & Tricks

### Performance Optimization

1. **Disable unused plugins** - Reduces memory usage
2. **Adjust cache settings** - Balance speed vs memory
3. **Use appropriate OCR backend** - EasyOCR is fastest

### Productivity Tips

1. **Pin frequently used plugins** - Right-click in activity bar
2. **Use search** - Faster than browsing
3. **Learn hotkeys** - Instant access without mouse

### Customization

1. **Create custom dashboard** - Arrange widgets as you like
2. **Configure auto-hide** - Activity bar hides when not in use
3. **Adjust transparency** - Match your game aesthetic

---

## FAQ

### Q: EU-Utility doesn't start

**A:** Check:
1. Python 3.11+ is installed
2. All dependencies are installed: `pip install -r requirements.txt`
3. Check logs in `logs/` directory

### Q: Hotkeys don't work

**A:** 
1. Check if another application is using the same hotkeys
2. Run as administrator (Windows)
3. Verify hotkeys in Settings → Hotkeys

### Q: OCR not working

**A:**
1. Install OCR backend: `pip install easyocr`
2. Check if Tesseract is in PATH (if using pytesseract)
3. Verify screen region is correct

### Q: Overlay doesn't stay on top

**A:**
1. Check "Always on top" in settings
2. Some games may prevent overlays - run EU-Utility as administrator

### Q: How do I update EU-Utility?

**A:**
```bash
git pull origin main
pip install -r requirements.txt --upgrade
```

### Q: Can I create my own plugins?

**A:** Yes! See [Plugin Development Guide](./docs/PLUGIN_DEVELOPMENT_GUIDE.md)

### Q: Where is my data stored?

**A:**
- Settings: `config/settings.json`
- Plugin data: `data/`
- Logs: `logs/`

### Q: Is EU-Utility safe to use?

**A:** Yes. EU-Utility:
- Only reads game data (logs, screen)
- Doesn't modify game files
- Doesn't inject code into the game
- Is open source - you can verify the code

### Q: How do I report bugs?

**A:** 
1. Check [Troubleshooting Guide](./TROUBLESHOOTING.md)
2. Open an issue on GitHub with:
   - EU-Utility version
   - Operating system
   - Steps to reproduce
   - Error logs

---

## Getting Help

- **Documentation:** Check `docs/` folder
- **Issues:** GitHub Issues
- **Discussions:** GitHub Discussions

---

**Happy hunting in Entropia Universe!** 🎮