impulsivefps
/
EU-Utility
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
EU-Utility/docs/TROUBLESHOOTING.md

14 KiB
Raw Blame History

EU-Utility Troubleshooting Guide

Solutions to common problems and issues

Version: 2.0
Last Updated: 2025-02-14

Table of Contents

  1. Installation Issues
  2. Startup Problems
  3. Hotkey Issues
  4. Overlay Problems
  5. Plugin Issues
  6. OCR Problems
  7. Spotify Issues
  8. Performance Issues
  9. Data Issues
  10. Getting Help

Installation Issues

"ModuleNotFoundError: No module named 'PyQt6'"

Problem: PyQt6 is not installed.

Solution:

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:

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

# Install Visual C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
# Or install just the C++ build tools workload

Linux:

sudo apt-get install python3-dev build-essential

Startup Problems

"EU-Utility won't start"

Check these steps:

  1. Check Python version:

    python --version
# Should be 3.11 or higher

  2. Check dependencies:

    pip list | grep -i pyqt

  3. Run with verbose output:

    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:

# Reinstall all dependencies
pip install --force-reinstall -r requirements.txt

"Qt platform plugin could not be initialized"

Problem: Missing Qt platform plugins.

Solution:

Windows:

# Set environment variable
set QT_QPA_PLATFORM_PLUGIN_PATH=C:\Python311\Lib\site-packages\PyQt6\Qt6\plugins\platforms

Linux:

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

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

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

    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:

    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:

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

# 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

# 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

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

    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

  2. Reduce capture region:

    # Capture smaller area
result = self.ocr_capture(region=(x, y, width, height))

  3. Lower quality for speed:

    # 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: 
    # In settings or config
ocr_engine = "tesseract"  # or "easyocr"

Spotify Issues

"Spotify not detected"

Solutions:

Linux

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

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

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

    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:

    # Windows
dir data\

# Linux
df -h data/

  2. Check permissions:

    # Linux
ls -la data/
# Should be writable by current user

  3. Check for errors:

    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:

    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:

    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:

    # Check README or version file
cat plugins/base_plugin.py | grep version

  2. Python version:

    python --version

  3. Operating system:

    # Windows
ver

# Linux
uname -a

  4. Error logs:

    python -m core.main 2>&1 | tee error.log

  5. Installed packages:

    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)

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

# 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

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