754 lines
14 KiB
Markdown
754 lines
14 KiB
Markdown
# EU-Utility Troubleshooting Guide
|
|
|
|
> Solutions to common problems and issues
|
|
>
|
|
> **Version:** 2.0
|
|
> **Last Updated:** 2025-02-14
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Installation Issues](#installation-issues)
|
|
2. [Startup Problems](#startup-problems)
|
|
3. [Hotkey Issues](#hotkey-issues)
|
|
4. [Overlay Problems](#overlay-problems)
|
|
5. [Plugin Issues](#plugin-issues)
|
|
6. [OCR Problems](#ocr-problems)
|
|
7. [Spotify Issues](#spotify-issues)
|
|
8. [Performance Issues](#performance-issues)
|
|
9. [Data Issues](#data-issues)
|
|
10. [Getting Help](#getting-help)
|
|
|
|
---
|
|
|
|
## Installation Issues
|
|
|
|
### "ModuleNotFoundError: No module named 'PyQt6'"
|
|
|
|
**Problem:** PyQt6 is not installed.
|
|
|
|
**Solution:**
|
|
```bash
|
|
pip install PyQt6
|
|
```
|
|
|
|
### "pip is not recognized"
|
|
|
|
**Problem:** Python is not in your PATH.
|
|
|
|
**Solution:**
|
|
1. Reinstall Python and check "Add Python to PATH"
|
|
2. Or add Python manually:
|
|
- Windows: Add `C:\Python311\` and `C:\Python311\Scripts\` to PATH
|
|
- Linux: Usually already in PATH
|
|
|
|
### "Permission denied" when installing
|
|
|
|
**Problem:** Insufficient permissions.
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Windows (Run as Administrator)
|
|
pip install -r requirements.txt
|
|
|
|
# Linux/Mac
|
|
sudo pip install -r requirements.txt
|
|
# Or use user install
|
|
pip install --user -r requirements.txt
|
|
```
|
|
|
|
### "Failed building wheel for ..."
|
|
|
|
**Problem:** Missing build tools.
|
|
|
|
**Solution:**
|
|
|
|
**Windows:**
|
|
```bash
|
|
# Install Visual C++ Build Tools
|
|
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
|
|
# Or install just the C++ build tools workload
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
sudo apt-get install python3-dev build-essential
|
|
```
|
|
|
|
---
|
|
|
|
## Startup Problems
|
|
|
|
### "EU-Utility won't start"
|
|
|
|
**Check these steps:**
|
|
|
|
1. **Check Python version:**
|
|
```bash
|
|
python --version
|
|
# Should be 3.11 or higher
|
|
```
|
|
|
|
2. **Check dependencies:**
|
|
```bash
|
|
pip list | grep -i pyqt
|
|
```
|
|
|
|
3. **Run with verbose output:**
|
|
```bash
|
|
python -m core.main 2>&1 | tee startup.log
|
|
```
|
|
|
|
4. **Check for conflicting processes:**
|
|
- Open Task Manager (Windows) or Activity Monitor (Mac)
|
|
- Look for existing EU-Utility processes
|
|
- End them and try again
|
|
|
|
### "ImportError: cannot import name '...'"
|
|
|
|
**Problem:** Corrupted or partial installation.
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Reinstall all dependencies
|
|
pip install --force-reinstall -r requirements.txt
|
|
```
|
|
|
|
### "Qt platform plugin could not be initialized"
|
|
|
|
**Problem:** Missing Qt platform plugins.
|
|
|
|
**Solution:**
|
|
|
|
**Windows:**
|
|
```bash
|
|
# Set environment variable
|
|
set QT_QPA_PLATFORM_PLUGIN_PATH=C:\Python311\Lib\site-packages\PyQt6\Qt6\plugins\platforms
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
# Install platform plugins
|
|
sudo apt-get install qtbase5-dev
|
|
```
|
|
|
|
### "Floating icon not appearing"
|
|
|
|
**Problem:** Icon may be off-screen or hidden.
|
|
|
|
**Solution:**
|
|
1. Check system tray (may be minimized)
|
|
2. Reset position by deleting settings:
|
|
```bash
|
|
# Windows
|
|
del data\settings.json
|
|
|
|
# Linux
|
|
rm data/settings.json
|
|
```
|
|
3. Restart EU-Utility
|
|
|
|
---
|
|
|
|
## Hotkey Issues
|
|
|
|
### "Hotkeys not working"
|
|
|
|
**Common causes and solutions:**
|
|
|
|
#### 1. Keyboard library not installed
|
|
```bash
|
|
pip install keyboard
|
|
```
|
|
|
|
#### 2. Need Administrator privileges (Windows)
|
|
- Right-click on EU-Utility
|
|
- Select "Run as administrator"
|
|
|
|
#### 3. Conflicting hotkeys
|
|
- Check if other apps use the same hotkeys
|
|
- Change hotkeys in Settings
|
|
|
|
#### 4. Keyboard layout issues
|
|
- Some hotkeys may not work on non-US layouts
|
|
- Try different key combinations
|
|
|
|
### "Hotkeys work intermittently"
|
|
|
|
**Problem:** Focus or timing issues.
|
|
|
|
**Solutions:**
|
|
1. Ensure game window is focused
|
|
2. Try pressing hotkeys more deliberately
|
|
3. Check if antivirus is interfering
|
|
4. Disable Windows Game Mode (sometimes interferes)
|
|
|
|
### "Changed hotkey but still uses old one"
|
|
|
|
**Solution:**
|
|
1. Restart EU-Utility after changing hotkeys
|
|
2. Check if multiple instances are running
|
|
3. Reset settings:
|
|
```bash
|
|
rm data/settings.json
|
|
```
|
|
|
|
---
|
|
|
|
## Overlay Problems
|
|
|
|
### "Overlay not showing"
|
|
|
|
**Checklist:**
|
|
|
|
1. **Press toggle hotkey:** `Ctrl + Shift + U`
|
|
2. **Double-click floating icon**
|
|
3. **Check if hidden:**
|
|
- Press `Ctrl + Shift + H` to unhide
|
|
4. **Check opacity:**
|
|
- May be set to 0% in settings
|
|
- Reset: delete `data/settings.json`
|
|
|
|
### "Overlay shows but is blank"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check plugin selection:**
|
|
- Click on a plugin tab on the left
|
|
- First plugin may not have loaded
|
|
|
|
2. **Check for errors:**
|
|
```bash
|
|
python -m core.main 2>&1 | grep -i error
|
|
```
|
|
|
|
3. **Disable problematic plugin:**
|
|
- Start with `--safe-mode` (if available)
|
|
- Or delete `data/settings.json` to reset
|
|
|
|
### "Overlay disappears when clicking game"
|
|
|
|
**Problem:** Click-through or focus issue.
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check click-through setting:**
|
|
- Right-click floating icon
|
|
- Toggle "Click-through" mode
|
|
|
|
2. **Pin the overlay:**
|
|
- Look for pin button in overlay header
|
|
|
|
3. **Windows-specific:**
|
|
- Run EU-Utility as administrator
|
|
- Disable "Focus Assist" in Windows settings
|
|
|
|
### "Overlay is too small/big"
|
|
|
|
**Solution:**
|
|
1. Resize by dragging edges
|
|
2. Or set size in settings:
|
|
```json
|
|
{
|
|
"overlay_width": 800,
|
|
"overlay_height": 600
|
|
}
|
|
```
|
|
|
|
### "Overlay shows on wrong monitor"
|
|
|
|
**Solution:**
|
|
1. Drag overlay to desired monitor
|
|
2. Position is saved automatically
|
|
3. Or reset position:
|
|
```bash
|
|
rm data/settings.json
|
|
```
|
|
|
|
---
|
|
|
|
## Plugin Issues
|
|
|
|
### "Plugin not loading"
|
|
|
|
**Checklist:**
|
|
|
|
1. **Check plugin folder structure:**
|
|
```
|
|
plugins/my_plugin/
|
|
├── __init__.py
|
|
└── plugin.py
|
|
```
|
|
|
|
2. **Check for syntax errors:**
|
|
```bash
|
|
python -m py_compile plugins/my_plugin/plugin.py
|
|
```
|
|
|
|
3. **Check plugin is enabled:**
|
|
- Open Settings
|
|
- Go to Plugins tab
|
|
- Ensure checkbox is checked
|
|
|
|
4. **Check console output:**
|
|
```bash
|
|
python -m core.main 2>&1 | grep -i "plugin"
|
|
```
|
|
|
|
### "Plugin crashes on open"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check plugin code:**
|
|
- Look for missing imports
|
|
- Check for undefined variables
|
|
- Verify `get_ui()` returns a QWidget
|
|
|
|
2. **Enable debug mode:**
|
|
```python
|
|
# Add to your plugin
|
|
def get_ui(self):
|
|
try:
|
|
# Your code
|
|
except Exception as e:
|
|
print(f"[{self.name}] Error: {e}")
|
|
import traceback
|
|
traceback.print_exc()
|
|
```
|
|
|
|
3. **Test in isolation:**
|
|
- Disable all other plugins
|
|
- Test one plugin at a time
|
|
|
|
### "Plugin settings not saving"
|
|
|
|
**Solution:**
|
|
```python
|
|
# Ensure you're using the config dict
|
|
def initialize(self):
|
|
self.my_setting = self.get_config('my_setting', default_value)
|
|
|
|
def shutdown(self):
|
|
self.set_config('my_setting', self.my_setting)
|
|
super().shutdown()
|
|
```
|
|
|
|
### "Plugin hotkey not working"
|
|
|
|
**Checklist:**
|
|
1. Hotkey format: `"ctrl+shift+x"` (lowercase, no spaces)
|
|
2. Hotkey not used by another plugin
|
|
3. Plugin is enabled
|
|
4. No syntax errors in plugin
|
|
|
|
---
|
|
|
|
## OCR Problems
|
|
|
|
### "OCR not working / No text detected"
|
|
|
|
**Solutions:**
|
|
|
|
#### 1. Install OCR engine
|
|
```bash
|
|
# EasyOCR (recommended)
|
|
pip install easyocr
|
|
|
|
# Or Tesseract
|
|
pip install pytesseract
|
|
# Also install Tesseract OCR binary from:
|
|
# https://github.com/UB-Mannheim/tesseract/wiki
|
|
```
|
|
|
|
#### 2. First run initialization
|
|
EasyOCR downloads models on first use. This may take a few minutes.
|
|
|
|
#### 3. Check game window visibility
|
|
- Ensure game window is visible (not minimized)
|
|
- Try increasing game brightness
|
|
- Close other windows that might overlap
|
|
|
|
#### 4. Test OCR directly
|
|
```python
|
|
from core.ocr_service import get_ocr_service
|
|
|
|
ocr = get_ocr_service()
|
|
if ocr.is_available():
|
|
result = ocr.recognize()
|
|
print(result)
|
|
else:
|
|
print("OCR not available")
|
|
```
|
|
|
|
### "OCR is slow"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Use GPU (if available):**
|
|
```bash
|
|
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
|
|
```
|
|
|
|
2. **Reduce capture region:**
|
|
```python
|
|
# Capture smaller area
|
|
result = self.ocr_capture(region=(x, y, width, height))
|
|
```
|
|
|
|
3. **Lower quality for speed:**
|
|
```python
|
|
# In OCR service settings
|
|
ocr.use_gpu = False # If GPU is slower
|
|
```
|
|
|
|
### "OCR accuracy is poor"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Increase game resolution**
|
|
2. **Use larger text in game**
|
|
3. **Ensure good lighting in game**
|
|
4. **Try different OCR engine:**
|
|
```python
|
|
# In settings or config
|
|
ocr_engine = "tesseract" # or "easyocr"
|
|
```
|
|
|
|
---
|
|
|
|
## Spotify Issues
|
|
|
|
### "Spotify not detected"
|
|
|
|
**Solutions:**
|
|
|
|
#### Linux
|
|
```bash
|
|
# Install playerctl
|
|
sudo apt-get install playerctl
|
|
|
|
# Verify installation
|
|
playerctl --version
|
|
```
|
|
|
|
#### Windows
|
|
1. Ensure Spotify desktop app is running (not web player)
|
|
2. Try restarting Spotify
|
|
3. Check Windows Media Service is running
|
|
|
|
#### Mac
|
|
1. Ensure Spotify is running
|
|
2. Grant accessibility permissions if prompted
|
|
|
|
### "Spotify controls not working"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check Spotify is playing:**
|
|
- Start playing music first
|
|
- Then try controls
|
|
|
|
2. **Restart Spotify:**
|
|
- Close Spotify completely
|
|
- Reopen and start playing
|
|
- Try controls again
|
|
|
|
3. **Check permissions (Mac):**
|
|
- System Preferences > Security & Privacy > Accessibility
|
|
- Add EU-Utility/Terminal
|
|
|
|
### "Spotify shows 'Not playing'"
|
|
|
|
**Solutions:**
|
|
1. Start playing music in Spotify first
|
|
2. Wait a few seconds for detection
|
|
3. Check if private session is enabled (disable it)
|
|
|
|
---
|
|
|
|
## Performance Issues
|
|
|
|
### "EU-Utility is laggy"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Disable unused plugins:**
|
|
- Settings > Plugins
|
|
- Uncheck plugins you don't use
|
|
|
|
2. **Lower overlay opacity:**
|
|
- Settings > General
|
|
- Reduce opacity to 0.8 or lower
|
|
|
|
3. **Close overlay widgets:**
|
|
- Close floating widgets you're not using
|
|
|
|
4. **Reduce OCR frequency:**
|
|
- Don't use continuous OCR scanning
|
|
|
|
5. **Check CPU usage:**
|
|
```bash
|
|
# Windows
|
|
tasklist | findstr python
|
|
|
|
# Linux
|
|
top -p $(pgrep -d',' python)
|
|
```
|
|
|
|
### "High CPU usage"
|
|
|
|
**Common causes:**
|
|
|
|
1. **Too many plugins enabled**
|
|
2. **Continuous scanning**
|
|
3. **Background tasks running**
|
|
|
|
**Solutions:**
|
|
```python
|
|
# Add delays to periodic tasks
|
|
task_id = self.schedule_task(
|
|
delay_ms=0,
|
|
func=my_function,
|
|
periodic=True,
|
|
interval_ms=60000 # Every minute, not every second
|
|
)
|
|
```
|
|
|
|
### "Memory usage growing"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Clear event history:**
|
|
```python
|
|
from core.event_bus import get_event_bus
|
|
get_event_bus().clear_history()
|
|
```
|
|
|
|
2. **Limit data retention:**
|
|
- Settings > Data
|
|
- Set retention to 7 or 30 days
|
|
|
|
3. **Restart EU-Utility periodically**
|
|
|
|
---
|
|
|
|
## Data Issues
|
|
|
|
### "Data not saving"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check disk space:**
|
|
```bash
|
|
# Windows
|
|
dir data\
|
|
|
|
# Linux
|
|
df -h data/
|
|
```
|
|
|
|
2. **Check permissions:**
|
|
```bash
|
|
# Linux
|
|
ls -la data/
|
|
# Should be writable by current user
|
|
```
|
|
|
|
3. **Check for errors:**
|
|
```bash
|
|
python -m core.main 2>&1 | grep -i "save\|write\|permission"
|
|
```
|
|
|
|
### "Data corrupted"
|
|
|
|
**Solution:**
|
|
1. Backup `data/` folder
|
|
2. Delete corrupted files
|
|
3. Restore from backup if available
|
|
|
|
### "Lost all my data"
|
|
|
|
**Recovery options:**
|
|
|
|
1. **Check for backups:**
|
|
```bash
|
|
ls -la data/*.backup
|
|
ls -la data/*.json.bak
|
|
```
|
|
|
|
2. **Check recycle bin/trash**
|
|
|
|
3. **Use file recovery tools** (if recently deleted)
|
|
|
|
### "Import not working"
|
|
|
|
**Solutions:**
|
|
|
|
1. **Check file format:**
|
|
- Must be valid JSON
|
|
- Must match expected structure
|
|
|
|
2. **Validate JSON:**
|
|
```bash
|
|
python -m json.tool my_backup.json
|
|
```
|
|
|
|
3. **Check file encoding:**
|
|
- Must be UTF-8
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
### Collecting Information
|
|
|
|
Before asking for help, collect:
|
|
|
|
1. **EU-Utility version:**
|
|
```python
|
|
# Check README or version file
|
|
cat plugins/base_plugin.py | grep version
|
|
```
|
|
|
|
2. **Python version:**
|
|
```bash
|
|
python --version
|
|
```
|
|
|
|
3. **Operating system:**
|
|
```bash
|
|
# Windows
|
|
ver
|
|
|
|
# Linux
|
|
uname -a
|
|
```
|
|
|
|
4. **Error logs:**
|
|
```bash
|
|
python -m core.main 2>&1 | tee error.log
|
|
```
|
|
|
|
5. **Installed packages:**
|
|
```bash
|
|
pip list > packages.txt
|
|
```
|
|
|
|
### Where to Get Help
|
|
|
|
1. **Documentation:**
|
|
- Check `docs/` folder
|
|
- Read relevant plugin documentation
|
|
|
|
2. **Logs:**
|
|
- Check `data/logs/` for error logs
|
|
- Run with verbose output
|
|
|
|
3. **Community:**
|
|
- Entropia Universe forums
|
|
- Discord communities
|
|
- GitHub issues (if applicable)
|
|
|
|
### Reporting Bugs
|
|
|
|
When reporting bugs, include:
|
|
|
|
1. **What you were doing**
|
|
2. **What you expected to happen**
|
|
3. **What actually happened**
|
|
4. **Error messages** (copy-paste full error)
|
|
5. **Steps to reproduce**
|
|
6. **System information:**
|
|
- OS version
|
|
- Python version
|
|
- EU-Utility version
|
|
|
|
### Template
|
|
|
|
```
|
|
**Bug Report**
|
|
|
|
**Description:**
|
|
Brief description of the issue
|
|
|
|
**Steps to Reproduce:**
|
|
1. Step one
|
|
2. Step two
|
|
3. Step three
|
|
|
|
**Expected Behavior:**
|
|
What should happen
|
|
|
|
**Actual Behavior:**
|
|
What actually happens
|
|
|
|
**Error Message:**
|
|
```
|
|
Paste full error message here
|
|
```
|
|
|
|
**System Info:**
|
|
- OS: Windows 11 / Ubuntu 22.04 / etc.
|
|
- Python: 3.11.4
|
|
- EU-Utility: 2.0.0
|
|
|
|
**Additional Context:**
|
|
Any other relevant information
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Fixes
|
|
|
|
### Nuclear Option (Reset Everything)
|
|
|
|
```bash
|
|
# Backup first
|
|
cp -r data data.backup
|
|
|
|
# Reset settings
|
|
rm data/settings.json
|
|
|
|
# Reset all data (WARNING: Loses everything)
|
|
rm -rf data/*
|
|
|
|
# Restart EU-Utility
|
|
```
|
|
|
|
### Safe Mode Start
|
|
|
|
If EU-Utility won't start normally:
|
|
|
|
```bash
|
|
# Disable all plugins temporarily
|
|
mv plugins plugins_disabled
|
|
mkdir plugins
|
|
cp plugins_disabled/base_plugin.py plugins/
|
|
|
|
# Start EU-Utility
|
|
python -m core.main
|
|
|
|
# Re-enable plugins one by one
|
|
```
|
|
|
|
### Clean Reinstall
|
|
|
|
```bash
|
|
# 1. Backup data
|
|
cp -r data data_backup
|
|
|
|
# 2. Remove installation
|
|
rm -rf EU-Utility
|
|
|
|
# 3. Re-download and install
|
|
# (Follow installation instructions)
|
|
|
|
# 4. Restore data
|
|
cp -r data_backup/* EU-Utility/data/
|
|
```
|
|
|
|
---
|
|
|
|
**Still having issues?** Check the logs and ask for help with the information collected above.
|