489 lines
8.3 KiB
Markdown
489 lines
8.3 KiB
Markdown
# 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)
|