EU-Utility/core

EU-Utility Core Module

The core/ module contains the foundational functionality for EU-Utility, providing plugin management, API services, UI components, and utility functions.

Module Structure

core/
├── __init__.py                 # Package exports and version info
├── base_plugin.py              # BasePlugin abstract class
├── event_bus.py                # Typed event system
├── settings.py                 # Configuration management
├── plugin_api.py               # Backward compatibility wrapper
├── plugin_manager.py           # Plugin lifecycle management
│
├── api/                        # Three-tier API system
│   ├── __init__.py
│   ├── plugin_api.py           # PluginAPI - core services access
│   ├── widget_api.py           # WidgetAPI - overlay widgets
│   └── external_api.py         # ExternalAPI - third-party integrations
│
├── ui/                         # UI components
│   ├── __init__.py
│   ├── dashboard_view.py
│   ├── settings_view.py
│   └── search_view.py
│
└── utils/                      # Utility modules (to be created)
    ├── __init__.py
    ├── eu_styles.py            # Styling system
    ├── security_utils.py       # Security utilities
    └── helpers.py              # Common helpers

Key Components

1. BasePlugin (base_plugin.py)

Abstract base class that all plugins must inherit from.

from core.base_plugin import BasePlugin
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel

class MyPlugin(BasePlugin):
    name = "My Plugin"
    version = "1.0.0"
    author = "Your Name"
    description = "What my plugin does"
    hotkey = "ctrl+shift+y"
    
    def initialize(self) -> None:
        self.log_info("My Plugin initialized!")
    
    def get_ui(self) -> QWidget:
        widget = QWidget()
        layout = QVBoxLayout(widget)
        layout.addWidget(QLabel("Hello from My Plugin!"))
        return widget

2. EventBus (event_bus.py)

Typed event system for plugin communication.

from core.event_bus import get_event_bus, LootEvent, DamageEvent

bus = get_event_bus()

# Subscribe to events
sub_id = bus.subscribe_typed(
    LootEvent,
    handle_loot,
    mob_types=["Atrox", "Daikiba"]
)

# Publish events
bus.publish(LootEvent(
    mob_name="Atrox",
    items=[{"name": "Animal Oil", "value": 0.05}],
    total_tt_value=0.05
))

Available event types:

• SkillGainEvent - Skill increases
• LootEvent - Loot received
• DamageEvent - Combat damage
• GlobalEvent - Global announcements
• ChatEvent - Chat messages
• EconomyEvent - Economic transactions
• SystemEvent - System notifications

3. Settings (settings.py)

Configuration management with automatic persistence.

from core.settings import get_settings

settings = get_settings()

# Get/set values
theme = settings.get('overlay_theme', 'dark')
settings.set('overlay_theme', 'light')

# Plugin management
if settings.is_plugin_enabled('my_plugin'):
    settings.enable_plugin('my_plugin')

4. PluginAPI (api/plugin_api.py)

Primary API for accessing core services.

from core.api import get_api

api = get_api()

# Log reading
lines = api.read_log_lines(100)

# Window info
window = api.get_eu_window()

# OCR
text = api.recognize_text(region=(100, 100, 200, 50))

# Notifications
api.show_notification("Title", "Message")

# Data storage
api.set_data("key", value)
value = api.get_data("key", default)

Service Architecture

The core uses a service registration pattern:

1. Services are created during app initialization
2. Services register themselves with PluginAPI
3. Plugins access services through the unified API

Available Services

Service	Description	API Methods
Log Reader	Read game chat.log	read_log_lines()
Window Manager	EU window info	get_eu_window(), is_eu_focused()
OCR	Screen text recognition	recognize_text()
Screenshot	Screen capture	capture_screen()
Nexus API	Item database	search_items(), get_item_details()
HTTP Client	Web requests	http_get(), http_post()
Audio	Sound playback	play_sound()
Notifications	Toast notifications	show_notification()
Clipboard	Copy/paste	copy_to_clipboard(), paste_from_clipboard()
Event Bus	Pub/sub events	subscribe(), publish()
Data Store	Key-value storage	set_data(), get_data()
Tasks	Background execution	run_task()

Best Practices

For Plugin Developers

1. Always inherit from BasePlugin: Use the provided base class for consistent behavior
2. Use type hints: Add type annotations for better IDE support
3. Handle errors gracefully: Wrap external calls in try/except blocks
4. Clean up in shutdown(): Unsubscribe from events, close resources
5. Use the API: Access services through PluginAPI rather than direct imports

For Core Contributors

1. Maintain backward compatibility: Don't break existing plugin APIs
2. Add type hints: All public methods should have type annotations
3. Document thoroughly: Use docstrings with Args, Returns, Examples
4. Follow PEP 8: Consistent naming (snake_case for functions/variables)
5. Use lazy initialization: Expensive services should initialize on first use

Version History

Version	Changes
2.1.0	Added comprehensive type hints, improved documentation
2.0.0	Three-tier API architecture, typed EventBus
1.0.0	Initial release

See Also

• Plugin Development Guide
• API Reference
• Architecture Overview