# EU-Utility 🎮

> A versatile Entropia Universe utility suite with a modular plugin system

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](./CHANGELOG.md)
[![Python](https://img.shields.io/badge/python-3.11+-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg)]()

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

![EU-Utility Screenshot](assets/screenshot.png)

---

## ✨ Features

- **🎮 Global Hotkey Overlay** - Quick access with customizable keyboard shortcuts
- **🔌 Modular Plugin System** - 25+ built-in plugins, create your own
- **🔍 Universal Search** - Search Entropia Nexus for items, mobs, locations instantly
- **🧮 Smart Calculators** - DPP, crafting, enhancer calculations
- **📊 Comprehensive Trackers** - Loot, skills, missions, codex, globals, and more
- **🎵 Media Integration** - Spotify control without alt-tabbing
- **📷 OCR Game Scanner** - Read in-game text directly
- **📈 Real-time Data** - Live market data via Nexus API

---

## 📋 Table of Contents

- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Hotkeys](#-hotkeys)
- [Plugins](#-plugins)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [Changelog](./CHANGELOG.md)
- [License](#-license)

---

## 🚀 Installation

### Prerequisites

- **Python 3.11 or higher**
- **Windows 10/11** (full support) or **Linux** (limited support)
- **Entropia Universe** (optional, for game integration features)

### Step 1: Download

```bash
git clone https://github.com/ImpulsiveFPS/EU-Utility.git
cd EU-Utility
```

### Step 2: Install Dependencies

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

### Step 3: Launch

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

> 💡 **Tip:** The floating icon will appear on your screen. Double-click it to open the main overlay.

---

## 🏁 Quick Start

### First Launch

1. **Start EU-Utility** - Run `python -m core.main`
2. **Floating Icon Appears** - A small icon appears on your screen
3. **Double-click** to open the main overlay
4. **Use hotkeys** for instant access (see below)

### The Floating Icon

The floating icon is your quick access point to EU-Utility:

| Action | Result |
|--------|--------|
| **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:

- **📑 Plugin tabs** on the left - Switch between plugins
- **📋 Plugin content** in the center - The active plugin's interface
- **⚡ Quick actions** at the bottom - Common shortcuts

---

## ⌨️ Hotkeys

Global hotkeys work even when EU-Utility is hidden:

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

> 📝 **Customize hotkeys** in Settings → Hotkeys

---

## 🔌 Plugins

EU-Utility comes with **25 built-in plugins** organized by category:

### 🏠 Dashboard & Utility

| Plugin | Description | Hotkey |
|--------|-------------|--------|
| **Dashboard** | Customizable start page with avatar stats | `Ctrl+Shift+Home` |
| **Calculator** | Standard calculator | `Ctrl+Shift+C` |
| **Settings** | Configure EU-Utility preferences | `Ctrl+Shift+,` |
| **Plugin Store** | Community plugin marketplace | - |

### 🔍 Search & Information

| Plugin | Description | Hotkey |
|--------|-------------|--------|
| **Universal Search** | Search all Nexus entities (items, mobs, locations) | `Ctrl+Shift+F` |
| **Nexus Search** | Search items and market data | `Ctrl+Shift+N` |
| **TP Runner** | Teleporter locations and route planner | - |

### 🧮 Calculators

| Plugin | Description | Hotkey |
|--------|-------------|--------|
| **DPP Calculator** | Damage Per PEC and weapon efficiency | `Ctrl+Shift+D` |
| **Crafting Calc** | Blueprint calculator with success rates | `Ctrl+Shift+B` |
| **Enhancer Calc** | Enhancer break rates and costs | `Ctrl+Shift+E` |

### 📊 Trackers

| Plugin | Description | Hotkey |
|--------|-------------|--------|
| **Loot Tracker** | Track hunting loot with ROI analysis | `Ctrl+Shift+L` |
| **Skill Scanner** | OCR-based skill tracking | `Ctrl+Shift+S` |
| **Codex Tracker** | Creature challenge progress | `Ctrl+Shift+X` |
| **Mission Tracker** | Mission and objective tracking | - |
| **Global Tracker** | Track globals, HOFs, and ATHs | - |
| **Mining Helper** | Mining claims and hotspot tracking | - |
| **Auction Tracker** | Price and markup tracking | - |
| **Inventory Manager** | TT value and item management | - |
| **Profession Scanner** | Profession rank tracking | - |

### 🎮 Game Integration

| Plugin | Description | Hotkey |
|--------|-------------|--------|
| **Game Reader** | OCR for in-game menus and text | `Ctrl+Shift+R` |
| **Chat Logger** | Log, search, and filter chat | - |
| **Event Bus Example** | Demonstrates event system | - |

### 🎵 External Integration

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

---

## 📚 Documentation

Comprehensive documentation is available in the `docs/` folder:

| Document | Description |
|----------|-------------|
| [User Manual](./docs/USER_MANUAL.md) | Complete user guide |
| [Plugin Development Guide](./docs/PLUGIN_DEVELOPMENT_GUIDE.md) | Create custom plugins |
| [API Reference](./docs/API_REFERENCE.md) | Core services API |
| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues & solutions |
| [Nexus API Reference](./docs/NEXUS_API_REFERENCE.md) | Nexus integration |
| [Security Hardening](./docs/SECURITY_HARDENING_GUIDE.md) | Security best practices |
| [Plugin Development](./docs/PLUGIN_DEVELOPMENT.md) | Quick-start guide |
| [Nexus Usage Examples](./docs/NEXUS_USAGE_EXAMPLES.md) | API usage samples |
| [Nexus Linktree](./docs/NEXUS_LINKTREE.md) | Nexus resource links |
| [Task Service](./docs/TASK_SERVICE.md) | Background tasks |

---

## 🔧 Plugin Development

Create your own plugins to extend EU-Utility:

```python
from plugins.base_plugin import BasePlugin
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel

class MyPlugin(BasePlugin):
    """My first EU-Utility plugin."""
    
    name = "My Plugin"
    version = "1.0.0"
    author = "Your Name"
    description = "What my plugin does"
    hotkey = "ctrl+shift+y"
    
    def initialize(self):
        self.log_info("My Plugin initialized!")
    
    def get_ui(self):
        widget = QWidget()
        layout = QVBoxLayout(widget)
        layout.addWidget(QLabel("Hello from My Plugin!"))
        return widget
```

See [Plugin Development Guide](./docs/PLUGIN_DEVELOPMENT_GUIDE.md) for complete documentation.

---

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

### Quick Start for Contributors

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/EU-Utility.git
cd EU-Utility

# Create branch
git checkout -b feature/my-feature

# Make changes and test
python -m pytest

# Commit and push
git commit -m "Add my feature"
git push origin feature/my-feature

# Open Pull Request
```

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

---

## 🙏 Acknowledgments

- **Entropia Nexus** - For the comprehensive API and game data
- **MindArk** - Creators of Entropia Universe
- **Community Contributors** - Plugin developers and testers

---

## 📞 Support

- **Documentation:** Check the `docs/` folder
- **Issues:** Open a GitHub issue
- **Discussions:** Join our community Discord

---

<p align="center">
  Made with ❤️ by <strong>ImpulsiveFPS</strong> + <strong>Entropia Nexus</strong>
</p>

<p align="center">
  <sub>EU-Utility is an unofficial tool and is not affiliated with MindArk PE AB.</sub>
</p>