195 lines
5.7 KiB
Markdown
195 lines
5.7 KiB
Markdown
# 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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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](../../docs/PLUGIN_DEVELOPMENT_GUIDE.md)
|
|
- [API Reference](../../docs/API_REFERENCE.md)
|
|
- [Architecture Overview](../../docs/ARCHITECTURE.md)
|