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