EU-Utility/docs/SETUP_INSTRUCTIONS.md

EU-Utility Setup Instructions

Complete setup guide for EU-Utility.

Table of Contents

1. Prerequisites
2. Windows Setup
3. Linux Setup
4. Development Setup
5. Configuration
6. Verification
7. 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:

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:

git --version

Step 3: Clone Repository

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

Step 4: Install Dependencies

pip install -r requirements.txt

Step 5: Install OCR (Optional)

pip install easyocr

Or for Tesseract:

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:

@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:

sudo apt update
sudo apt install python3.11 python3-pip python3.11-venv git

Fedora:

sudo dnf install python3.11 python3-pip git

Arch:

sudo pacman -S python python-pip git

Step 2: Clone Repository

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

Step 3: Create Virtual Environment (Recommended)

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

Step 4: Install Dependencies

pip install -r requirements.txt

Step 5: Install System Dependencies

Ubuntu/Debian:

sudo apt install python3-pyqt6 libxcb-xinerama0 libxcb-cursor0

Fedora:

sudo dnf install python3-qt6 libxcb

Step 6: Install OCR (Optional)

pip install easyocr

Or for Tesseract:

sudo apt install tesseract-ocr
pip install pytesseract

Step 7: Create Desktop Entry (Optional)

Create ~/.local/share/applications/eu-utility.desktop:

[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

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

Step 2: Install Development Dependencies

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

Or install all at once:

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

Step 3: Install Pre-commit Hooks (Optional)

pip install pre-commit
pre-commit install

Step 4: Run Tests

# 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:

{
  "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:

{
  "enabled": [
    "plugins.calculator.plugin.CalculatorPlugin",
    "plugins.dashboard.plugin.DashboardPlugin"
  ],
  "settings": {
    "plugins.calculator.plugin.CalculatorPlugin": {
      "precision": 2
    }
  }
}

Environment Variables

# 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

# 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

python run_tests.py --unit

Step 3: Start Application

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:

# Use python3 explicitly
python3 --version
python3 -m pip install -r requirements.txt
python3 -m core.main

"No module named 'PyQt6'"

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

"Cannot connect to X server" (Linux)

# If running over SSH
export DISPLAY=:0

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

Permission denied errors

# 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

# 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

# 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:

   python -m pip install --upgrade pip
   

4. Reinstall dependencies:

   pip install -r requirements.txt --force-reinstall
   

---

Uninstallation

Remove EU-Utility

# 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