# EU-Utility Setup Instructions

Complete setup guide for EU-Utility.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Windows Setup](#windows-setup)
3. [Linux Setup](#linux-setup)
4. [Development Setup](#development-setup)
5. [Configuration](#configuration)
6. [Verification](#verification)
7. [Troubleshooting](#troubleshooting)

---

## Prerequisites

### Required

- **Python 3.11 or higher**
- **pip** (Python package manager)
- **Git** (for cloning repository)

### Optional (for full functionality)

- **OCR Engine** - EasyOCR, Tesseract, or PaddleOCR
- **Visual C++ Redistributables** (Windows)

---

## Windows Setup

### Step 1: Install Python

1. Download Python 3.11+ from https://python.org/downloads
2. Run installer
3. **Important:** Check "Add Python to PATH"
4. Click "Install Now"

Verify installation:
```cmd
python --version
# Should show Python 3.11.x or higher
```

### Step 2: Install Git

1. Download from https://git-scm.com/download/win
2. Run installer with default settings
3. Verify:
```cmd
git --version
```

### Step 3: Clone Repository

```cmd
cd %USERPROFILE%\Documents
git clone https://github.com/ImpulsiveFPS/EU-Utility.git
cd EU-Utility
```

### Step 4: Install Dependencies

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

### Step 5: Install OCR (Optional)

```cmd
pip install easyocr
```

Or for Tesseract:
```cmd
pip install pytesseract
```

Then download and install Tesseract from:
https://github.com/UB-Mannheim/tesseract/wiki

### Step 6: Create Shortcuts (Optional)

Create a batch file `start_eu.bat`:
```batch
@echo off
cd /d %~dp0
python -m core.main
```

Or create a Windows shortcut:
1. Right-click → New → Shortcut
2. Target: `pythonw -m core.main`
3. Start in: `C:\path\to\EU-Utility`

---

## Linux Setup

### Step 1: Install Python

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3.11 python3-pip python3.11-venv git
```

**Fedora:**
```bash
sudo dnf install python3.11 python3-pip git
```

**Arch:**
```bash
sudo pacman -S python python-pip git
```

### Step 2: Clone Repository

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

### Step 3: Create Virtual Environment (Recommended)

```bash
python3.11 -m venv venv
source venv/bin/activate
```

### Step 4: Install Dependencies

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

### Step 5: Install System Dependencies

**Ubuntu/Debian:**
```bash
sudo apt install python3-pyqt6 libxcb-xinerama0 libxcb-cursor0
```

**Fedora:**
```bash
sudo dnf install python3-qt6 libxcb
```

### Step 6: Install OCR (Optional)

```bash
pip install easyocr
```

Or for Tesseract:
```bash
sudo apt install tesseract-ocr
pip install pytesseract
```

### Step 7: Create Desktop Entry (Optional)

Create `~/.local/share/applications/eu-utility.desktop`:
```ini
[Desktop Entry]
Name=EU-Utility
Comment=Entropia Universe Utility
Exec=/home/username/EU-Utility/venv/bin/python -m core.main
Icon=/home/username/EU-Utility/assets/icon.png
Type=Application
Categories=Game;Utility;
```

---

## Development Setup

### Step 1: Clone with Development Tools

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

### Step 2: Install Development Dependencies

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

Or install all at once:
```bash
pip install -r requirements.txt -r requirements-dev.txt
```

### Step 3: Install Pre-commit Hooks (Optional)

```bash
pip install pre-commit
pre-commit install
```

### Step 4: Run Tests

```bash
# All tests
python run_tests.py --all

# Unit tests only
python run_tests.py --unit

# With coverage
python run_tests.py --unit --coverage
```

### Step 5: Setup IDE

**VS Code:**
1. Install Python extension
2. Select Python interpreter
3. Install recommended extensions from `.vscode/extensions.json`

**PyCharm:**
1. Open project folder
2. Configure Python interpreter
3. Set run configuration for `core/main.py`

---

## Configuration

### Initial Configuration

EU-Utility creates default configs on first run. You can customize:

**config/settings.json:**
```json
{
  "hotkeys": {
    "toggle": "ctrl+shift+u",
    "hide": "ctrl+shift+h"
  },
  "theme": {
    "mode": "dark",
    "accent_color": "#ff8c42"
  },
  "overlay": {
    "opacity": 0.95,
    "always_on_top": true
  }
}
```

**config/plugins.json:**
```json
{
  "enabled": [
    "plugins.calculator.plugin.CalculatorPlugin",
    "plugins.dashboard.plugin.DashboardPlugin"
  ],
  "settings": {
    "plugins.calculator.plugin.CalculatorPlugin": {
      "precision": 2
    }
  }
}
```

### Environment Variables

```bash
# Debug mode
export EU_DEBUG=1

# Custom config path
export EU_CONFIG_PATH=/path/to/config

# Disable GPU acceleration (if having issues)
export QT_QUICK_BACKEND=software

# HiDPI scaling
export QT_AUTO_SCREEN_SCALE_FACTOR=1
export QT_SCALE_FACTOR=1.5
```

### Directory Structure

```
EU-Utility/
├── config/           # Configuration files
├── data/             # Plugin data and cache
├── logs/             # Log files
├── plugins/          # Built-in plugins
├── user_plugins/     # User-installed plugins
├── assets/           # Images, icons, sounds
├── core/             # Core application code
├── tests/            # Test suite
├── requirements.txt  # Python dependencies
└── run_tests.py      # Test runner
```

---

## Verification

### Step 1: Check Installation

```bash
# Run verification script
python -c "
import sys
print(f'Python: {sys.version}')

try:
    from PyQt6.QtWidgets import QApplication
    print('✓ PyQt6 installed')
except ImportError:
    print('✗ PyQt6 missing')

try:
    import requests
    print('✓ requests installed')
except ImportError:
    print('✗ requests missing')

try:
    import PIL
    print('✓ Pillow installed')
except ImportError:
    print('✗ Pillow missing')

try:
    import easyocr
    print('✓ EasyOCR installed (optional)')
except ImportError:
    print('⚠ EasyOCR not installed (optional)')
"
```

### Step 2: Run Unit Tests

```bash
python run_tests.py --unit
```

### Step 3: Start Application

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

You should see:
1. Floating icon appears
2. System tray icon appears
3. Double-click floating icon opens overlay

### Step 4: Test Basic Functionality

1. **Test hotkeys:** Press `Ctrl+Shift+U` to toggle overlay
2. **Test plugins:** Click on different plugins in sidebar
3. **Test settings:** Open Settings and make changes
4. **Check logs:** `tail -f logs/eu_utility.log`

---

## Troubleshooting

### "Python is not recognized"

**Windows:**
1. Reinstall Python and check "Add to PATH"
2. Or use: `py -3.11` instead of `python`

**Linux:**
```bash
# Use python3 explicitly
python3 --version
python3 -m pip install -r requirements.txt
python3 -m core.main
```

### "No module named 'PyQt6'"

```bash
pip install PyQt6
# Or specific version
pip install PyQt6==6.6.1
```

### "Cannot connect to X server" (Linux)

```bash
# If running over SSH
export DISPLAY=:0

# If using Wayland, try X11
QT_QPA_PLATFORM=xcb python -m core.main
```

### Permission denied errors

```bash
# Fix permissions
chmod -R u+rw config data logs

# Or run with sudo (not recommended)
sudo chown -R $USER:$USER config data logs
```

### Tests fail

```bash
# Check pytest installation
pip install pytest pytest-qt

# Run with verbose output
python run_tests.py --unit -v

# Check specific test
python -m pytest tests/unit/test_plugin_manager.py -v
```

---

## Updating

### Update EU-Utility

```bash
# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt --upgrade

# Run tests
python run_tests.py --unit
```

### Update Python

1. Download new Python version
2. Install
3. Update pip:
   ```bash
   python -m pip install --upgrade pip
   ```
4. Reinstall dependencies:
   ```bash
   pip install -r requirements.txt --force-reinstall
   ```

---

## Uninstallation

### Remove EU-Utility

```bash
# Deactivate virtual environment (if used)
deactivate

# Remove directory
cd ..
rm -rf EU-Utility

# Remove config (optional)
rm -rf ~/.config/EU-Utility  # Linux
rm -rf %APPDATA%\EU-Utility   # Windows
```

---

## Next Steps

1. **Read User Guide:** `docs/USER_GUIDE.md`
2. **Configure Hotkeys:** Settings → Hotkeys
3. **Enable Plugins:** Settings → Plugins
4. **Customize Dashboard:** Drag and drop widgets

---

**Need help?** See [Troubleshooting Guide](./TROUBLESHOOTING.md)