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

992 lines
22 KiB
Markdown
Raw Blame History

# EU-Utility API Reference
> Complete API documentation for plugin developers
**Version:** 2.1.0
**Last Updated:** 2026-02-16
---
## Table of Contents
1. [Getting Started](#getting-started)
2. [PluginAPI](#pluginapi) - Core services access
3. [WidgetAPI](#widgetapi) - Overlay widget management
4. [ExternalAPI](#externalapi) - REST endpoints and webhooks
5. [Event Bus](#event-bus) - Pub/sub event system
6. [BasePlugin Class](#baseplugin-class) - Plugin base class reference
7. [Nexus API](#nexus-api) - Entropia Nexus integration
8. [Code Examples](#code-examples) - Practical examples
9. [Best Practices](#best-practices)
---
## Getting Started
### Importing the API
```python
from core.api import get_api
class MyPlugin(BasePlugin):
def initialize(self):
self.api = get_api()
```
### API Availability
Always check if a service is available before using it:
```python
if self.api.ocr_available():
text = self.api.recognize_text()
```
---
## PluginAPI
The PluginAPI provides access to all core EU-Utility services.
### Window Manager
```python
# Get EU window information
window = api.get_eu_window()
if window:
print(f"Position: {window['x']}, {window['y']}")
print(f"Size: {window['width']}x{window['height']}")
print(f"Focused: {window['is_focused']}")
# Check if EU is focused
if api.is_eu_focused():
api.play_sound("alert.wav")
# Bring EU to front
api.bring_eu_to_front()
# Check if EU window is visible
is_visible = api.is_eu_visible()
```
### OCR Service
```python
# Check OCR availability
if api.ocr_available():
# Read text from screen region
text = api.recognize_text(region=(100, 100, 200, 50))
print(f"Found: {text}")
# Alternative: Use BasePlugin helper method
result = self.ocr_capture(region=(x, y, width, height))
# Returns: {'text': str, 'confidence': float, 'error': str or None}
```
### Screenshot Service
```python
# Check availability
if api.screenshot_available():
# Capture full screen
img = api.capture_screen()
# Capture specific region
img = api.capture_screen(region=(100, 100, 400, 300))
# Capture and save
img = api.capture_screen(
region=(100, 100, 400, 300),
save_path="screenshot.png"
)
# Alternative: Use BasePlugin helper
img = self.capture_screen(full_screen=True)
img = self.capture_region(x, y, width, height)
```
### Log Reader
```python
# Read recent log lines
lines = api.read_log_lines(count=100)
# Read logs since timestamp
from datetime import datetime, timedelta
recent = api.read_log_since(datetime.now() - timedelta(minutes=5))
# Alternative: Use BasePlugin helper
lines = self.read_log(lines=50, filter_text="loot")
```
### Data Store
```python
# Store data (scoped to plugin)
api.set_data("key", value)
# Retrieve with default
value = api.get_data("key", default=None)
# Delete data
api.delete_data("key")
# Alternative: Use BasePlugin helpers
self.save_data("key", value)
data = self.load_data("key", default=None)
self.delete_data("key")
```
### HTTP Client
```python
# GET request with caching
result = api.http_get(
"https://api.example.com/data",
cache=True,
cache_duration=3600 # 1 hour
)
if result['success']:
data = result['data']
else:
error = result['error']
# POST request
result = api.http_post(
"https://api.example.com/submit",
data={"key": "value"}
)
# Alternative: Use BasePlugin helper
response = self.http_get(url, cache_ttl=300, headers={})
```
### Audio
```python
# Play sound file
api.play_sound("assets/sounds/alert.wav", volume=0.7)
# Simple beep
api.beep()
# Alternative: Use BasePlugin helpers
self.play_sound("hof") # Predefined: 'hof', 'skill_gain', 'alert'
self.set_volume(0.8)
volume = self.get_volume()
```
### Notifications
```python
# Show toast notification
api.show_notification(
title="Loot Alert!",
message="You found something valuable!",
duration=5000, # milliseconds
sound=True
)
# Alternative: Use BasePlugin helpers
self.notify(title, message, notification_type='info', sound=False)
self.notify_info(title, message)
self.notify_success(title, message)
self.notify_warning(title, message)
self.notify_error(title, message, sound=True)
```
### Clipboard
```python
# Copy to clipboard
api.copy_to_clipboard("Text to copy")
# Paste from clipboard
text = api.paste_from_clipboard()
# Alternative: Use BasePlugin helpers
self.copy_to_clipboard(text)
text = self.paste_from_clipboard()
```
### Background Tasks
```python
# Run function in background
def heavy_computation(data):
# Long running task
import time
time.sleep(2)
return f"Processed: {data}"
def on_complete(result):
print(f"Done: {result}")
def on_error(error):
print(f"Error: {error}")
task_id = api.run_task(
heavy_computation,
"my data",
callback=on_complete,
error_handler=on_error
)
# Cancel task
api.cancel_task(task_id)
# Alternative: Use BasePlugin helper
self.run_in_background(func, *args, priority='normal',
on_complete=cb, on_error=err_cb)
```
---
## WidgetAPI
Manage overlay widgets - floating UI components.
### Getting Started
```python
from core.api import get_widget_api
widget_api = get_widget_api()
# Create widget
widget = widget_api.create_widget(
name="loot_tracker",
title="Loot Tracker",
size=(400, 300),
position=(100, 100)
)
widget.show()
```
### Widget Operations
```python
# Show/hide
widget.show()
widget.hide()
# Position
widget.move(500, 200)
x, y = widget.position
# Size
widget.resize(400, 300)
width, height = widget.size
# Opacity (0.0 - 1.0)
widget.set_opacity(0.8)
# Lock/unlock (prevent dragging)
widget.set_locked(True)
# Minimize/restore
widget.minimize()
widget.restore()
# Close
widget.close()
```
### Widget Management
```python
# Get existing widget
widget = widget_api.get_widget("loot_tracker")
# Show/hide specific widget
widget_api.show_widget("loot_tracker")
widget_api.hide_widget("loot_tracker")
# Close widget
widget_api.close_widget("loot_tracker")
# Global operations
widget_api.show_all_widgets()
widget_api.hide_all_widgets()
widget_api.close_all_widgets()
widget_api.set_all_opacity(0.8)
widget_api.lock_all()
widget_api.unlock_all()
```
### Layout Helpers
```python
# Arrange widgets
widget_api.arrange_widgets(layout="grid", spacing=10)
widget_api.arrange_widgets(layout="horizontal")
widget_api.arrange_widgets(layout="vertical")
widget_api.arrange_widgets(layout="cascade")
# Snap to grid
widget_api.snap_to_grid(grid_size=10)
```
### Widget Events
```python
# Handle events
widget.on('moved', lambda data: print(f"Moved to {data['x']}, {data['y']}"))
widget.on('resized', lambda data: print(f"Sized to {data['width']}x{data['height']}"))
widget.on('closing', lambda: print("Widget closing"))
widget.on('closed', lambda: print("Widget closed"))
widget.on('update', lambda data: print(f"Update: {data}"))
```
---
## ExternalAPI
REST endpoints, webhooks, and third-party integrations.
### Getting Started
```python
from core.api import get_external_api
ext = get_external_api()
# Start server
ext.start_server(port=8080)
# Check status
print(ext.get_status())
```
### REST Endpoints
```python
# Using decorator
@ext.endpoint("stats", methods=["GET"])
def get_stats():
return {"kills": 100, "loot": "50 PED"}
@ext.endpoint("loot", methods=["POST"])
def record_loot(data):
save_loot(data)
return {"status": "saved"}
# Programmatic registration
def get_stats_handler(params):
return {"kills": 100}
ext.register_endpoint("stats", get_stats_handler, methods=["GET"])
# Unregister
ext.unregister_endpoint("stats")
```
### Incoming Webhooks
```python
# Register webhook handler
def handle_discord(payload):
print(f"Discord: {payload}")
return {"status": "ok"}
ext.register_webhook(
name="discord",
handler=handle_discord,
secret="my_secret" # Optional HMAC verification
)
# POST to: http://localhost:8080/webhook/discord
```
### Outgoing Webhooks
```python
# POST to external webhook
result = ext.post_webhook(
"https://discord.com/api/webhooks/...",
{"content": "Hello from EU-Utility!"}
)
if result['success']:
print("Sent!")
else:
print(f"Error: {result['error']}")
```
---
## Event Bus
Typed publish-subscribe event system for inter-plugin communication.
### Event Types
```python
from core.event_bus import (
SkillGainEvent,
LootEvent,
DamageEvent,
GlobalEvent,
ChatEvent,
EconomyEvent,
SystemEvent
)
```
### Publishing Events
```python
from core.event_bus import LootEvent, SkillGainEvent
# Publish loot event
self.publish_typed(LootEvent(
mob_name="Daikiba",
items=[{"name": "Animal Oil", "value": 0.05}],
total_tt_value=0.05
))
# Publish skill gain
self.publish_typed(SkillGainEvent(
skill_name="Rifle",
skill_value=25.5,
gain_amount=0.01
))
# Legacy event publishing
api.publish("my_plugin.event", {"data": "value"})
```
### Subscribing to Events
```python
from core.event_bus import LootEvent, SkillGainEvent
class MyPlugin(BasePlugin):
def initialize(self):
# Subscribe to loot events
self.sub_id = self.subscribe_typed(
LootEvent,
self.on_loot
)
# Subscribe with filtering
self.sub_id2 = self.subscribe_typed(
LootEvent,
self.on_dragon_loot,
mob_types=["Dragon", "Drake"]
)
# Subscribe to specific skills
self.sub_id3 = self.subscribe_typed(
SkillGainEvent,
self.on_combat_skill,
skill_names=["Rifle", "Pistol", "Melee"]
)
def on_loot(self, event: LootEvent):
print(f"Loot from {event.mob_name}: {event.items}")
def on_dragon_loot(self, event: LootEvent):
print(f"Dragon loot! Total TT: {event.total_tt_value}")
def shutdown(self):
# Clean up subscriptions
self.unsubscribe_typed(self.sub_id)
self.unsubscribe_typed(self.sub_id2)
self.unsubscribe_typed(self.sub_id3)
# Or: self.unsubscribe_all_typed()
```
### Event Attributes
| Event | Attributes |
|-------|------------|
| `SkillGainEvent` | `skill_name`, `skill_value`, `gain_amount` |
| `LootEvent` | `mob_name`, `items`, `total_tt_value`, `position` |
| `DamageEvent` | `damage_amount`, `damage_type`, `is_critical`, `target_name` |
| `GlobalEvent` | `player_name`, `achievement_type`, `value`, `item_name` |
| `ChatEvent` | `channel`, `sender`, `message` |
| `EconomyEvent` | `transaction_type`, `amount`, `currency`, `description` |
| `SystemEvent` | `message`, `severity` |
### Legacy Event Bus
```python
# Subscribe
sub_id = api.subscribe("loot", on_loot_callback)
# Unsubscribe
api.unsubscribe(sub_id)
# Publish
api.publish("event_type", {"key": "value"})
# Get history
history = api.get_event_history("loot", limit=10)
```
---
## BasePlugin Class
Complete reference for the base plugin class.
### Required Attributes
```python
class MyPlugin(BasePlugin):
name = "My Plugin" # Display name
version = "1.0.0" # Version string
author = "Your Name" # Author name
description = "..." # Short description
```
### Optional Attributes
```python
class MyPlugin(BasePlugin):
icon = "path/to/icon.png" # Icon path
hotkey = "ctrl+shift+y" # Legacy single hotkey
hotkeys = [ # Multi-hotkey format
{
'action': 'toggle',
'description': 'Toggle My Plugin',
'default': 'ctrl+shift+m',
'config_key': 'myplugin_toggle'
}
]
enabled = True # Start enabled
dependencies = { # Dependencies
'pip': ['requests', 'numpy'],
'plugins': ['other_plugin'],
'optional': {'pillow': 'Image processing'}
}
```
### Lifecycle Methods
```python
def initialize(self) -> None:
"""Called when plugin is loaded."""
self.api = get_api()
self.log_info("Initialized!")
def get_ui(self) -> QWidget:
"""Return the plugin's UI widget."""
widget = QWidget()
# ... setup UI ...
return widget
def on_show(self) -> None:
"""Called when overlay becomes visible."""
pass
def on_hide(self) -> None:
"""Called when overlay is hidden."""
pass
def on_hotkey(self) -> None:
"""Called when hotkey is pressed."""
pass
def shutdown(self) -> None:
"""Called when app is closing. Cleanup resources."""
self.unsubscribe_all_typed()
super().shutdown()
```
### Config Methods
```python
# Get config value
theme = self.get_config('theme', default='dark')
# Set config value
self.set_config('theme', 'light')
```
### Logging Methods
```python
self.log_debug("Debug message")
self.log_info("Info message")
self.log_warning("Warning message")
self.log_error("Error message")
```
### Utility Methods
```python
# Format currency
ped_text = self.format_ped(123.45) # "123.45 PED"
pec_text = self.format_pec(50) # "50 PEC"
# Calculate DPP
dpp = self.calculate_dpp(damage=45.0, ammo=100, decay=2.5)
# Calculate markup
markup = self.calculate_markup(price=150.0, tt=100.0) # 150.0%
```
---
## Nexus API
Entropia Nexus integration for game data.
### Searching
```python
# Search for items
results = self.nexus_search("ArMatrix", entity_type="items")
# Search for mobs
mobs = self.nexus_search("Atrox", entity_type="mobs")
# Search for locations
locations = self.nexus_search("Fort", entity_type="locations")
```
### Entity Types
- `items`, `weapons`, `armors`
- `mobs`, `pets`
- `blueprints`, `materials`
- `locations`, `teleporters`, `shops`, `vendors`, `planets`, `areas`
- `skills`
- `enhancers`, `medicaltools`, `finders`, `excavators`, `refiners`
- `vehicles`, `decorations`, `furniture`
- `storagecontainers`, `strongboxes`
### Getting Details
```python
# Get item details
details = self.nexus_get_item_details("armatrix_lp-35")
if details:
print(f"Name: {details['name']}")
print(f"TT Value: {details['tt_value']} PED")
# Get market data
market = self.nexus_get_market_data("armatrix_lp-35")
if market:
print(f"Current markup: {market['current_markup']:.1f}%")
```
---
## Code Examples
### Example 1: Simple Calculator Plugin
```python
from plugins.base_plugin import BasePlugin
from PyQt6.QtWidgets import (
QWidget, QVBoxLayout, QHBoxLayout,
QLabel, QLineEdit, QPushButton
)
class MarkupCalculatorPlugin(BasePlugin):
"""Calculate markup percentages."""
name = "Markup Calculator"
version = "1.0.0"
author = "Tutorial"
description = "Calculate item markup"
hotkey = "ctrl+shift+m"
def initialize(self):
self.log_info("Markup Calculator initialized!")
def get_ui(self):
widget = QWidget()
layout = QVBoxLayout(widget)
# Title
title = QLabel("Markup Calculator")
title.setStyleSheet("color: #4a9eff; font-size: 18px; font-weight: bold;")
layout.addWidget(title)
# TT Value input
layout.addWidget(QLabel("TT Value:"))
self.tt_input = QLineEdit()
self.tt_input.setPlaceholderText("100.00")
layout.addWidget(self.tt_input)
# Market Price input
layout.addWidget(QLabel("Market Price:"))
self.price_input = QLineEdit()
self.price_input.setPlaceholderText("150.00")
layout.addWidget(self.price_input)
# Calculate button
calc_btn = QPushButton("Calculate")
calc_btn.clicked.connect(self.calculate)
layout.addWidget(calc_btn)
# Result
self.result_label = QLabel("Markup: -")
self.result_label.setStyleSheet("color: #ffc107; font-size: 16px;")
layout.addWidget(self.result_label)
layout.addStretch()
return widget
def calculate(self):
try:
tt = float(self.tt_input.text() or 0)
price = float(self.price_input.text() or 0)
markup = self.calculate_markup(price, tt)
self.result_label.setText(f"Markup: {markup:.1f}%")
except ValueError:
self.result_label.setText("Invalid input")
```
### Example 2: Event-Driven Tracker
```python
from plugins.base_plugin import BasePlugin
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel, QListWidget
from core.event_bus import LootEvent, SkillGainEvent
class ActivityTrackerPlugin(BasePlugin):
"""Track recent activity from events."""
name = "Activity Tracker"
version = "1.0.0"
def initialize(self):
self.subscriptions = []
# Subscribe to multiple event types
sub1 = self.subscribe_typed(LootEvent, self.on_loot)
sub2 = self.subscribe_typed(SkillGainEvent, self.on_skill)
self.subscriptions.extend([sub1, sub2])
self.log_info("Activity Tracker initialized")
def get_ui(self):
widget = QWidget()
layout = QVBoxLayout(widget)
layout.addWidget(QLabel("Recent Activity:"))
self.activity_list = QListWidget()
layout.addWidget(self.activity_list)
return widget
def on_loot(self, event: LootEvent):
text = f"Loot: {event.mob_name} - {event.total_tt_value:.2f} PED"
self.activity_list.insertItem(0, text)
def on_skill(self, event: SkillGainEvent):
text = f"Skill: {event.skill_name} +{event.gain_amount:.4f}"
self.activity_list.insertItem(0, text)
def shutdown(self):
for sub_id in self.subscriptions:
self.unsubscribe_typed(sub_id)
```
### Example 3: Background Task Plugin
```python
from plugins.base_plugin import BasePlugin
from PyQt6.QtWidgets import (
QWidget, QVBoxLayout, QPushButton,
QLabel, QProgressBar
)
class DataFetcherPlugin(BasePlugin):
"""Fetch data in background."""
name = "Data Fetcher"
version = "1.0.0"
def initialize(self):
self.log_info("Data Fetcher initialized")
def get_ui(self):
widget = QWidget()
layout = QVBoxLayout(widget)
self.status_label = QLabel("Ready")
layout.addWidget(self.status_label)
self.progress = QProgressBar()
self.progress.setRange(0, 0) # Indeterminate
self.progress.hide()
layout.addWidget(self.progress)
fetch_btn = QPushButton("Fetch Data")
fetch_btn.clicked.connect(self.fetch_data)
layout.addWidget(fetch_btn)
layout.addStretch()
return widget
def fetch_data(self):
self.status_label.setText("Fetching...")
self.progress.show()
# Run in background
self.run_in_background(
self._fetch_from_api,
priority='normal',
on_complete=self._on_fetch_complete,
on_error=self._on_fetch_error
)
def _fetch_from_api(self):
# This runs in background thread
import time
time.sleep(2) # Simulate API call
return {"items": ["A", "B", "C"], "count": 3}
def _on_fetch_complete(self, result):
# This runs in main thread - safe to update UI
self.progress.hide()
self.status_label.setText(f"Got {result['count']} items")
self.notify_success("Data Fetched", f"Retrieved {result['count']} items")
def _on_fetch_error(self, error):
self.progress.hide()
self.status_label.setText(f"Error: {error}")
self.notify_error("Fetch Failed", str(error))
```
---
## Best Practices
### 1. Always Use BasePlugin Helpers
```python
# ✅ Good - Uses helper methods
self.save_data("key", value)
data = self.load_data("key", default)
# ❌ Avoid - Direct API access when helper exists
self.api.set_data("key", value)
```
### 2. Handle Errors Gracefully
```python
def initialize(self):
try:
self.api = get_api()
self.log_info("API connected")
except Exception as e:
self.log_error(f"Failed to get API: {e}")
# Continue with limited functionality
```
### 3. Clean Up Resources
```python
def shutdown(self):
# Unsubscribe from events
self.unsubscribe_all_typed()
# Save any pending data
self.save_data("pending", self.pending_data)
super().shutdown()
```
### 4. Don't Block the Main Thread
```python
# ✅ Good - Use background tasks
def heavy_operation(self):
self.run_in_background(
self._do_heavy_work,
on_complete=self._update_ui
)
# ❌ Avoid - Blocks UI
def heavy_operation(self):
result = self._do_heavy_work() # Blocks!
self._update_ui(result)
```
### 5. Use Type Hints
```python
from typing import Optional, Dict, Any, List
from core.event_bus import LootEvent
def on_loot(self, event: LootEvent) -> None:
items: List[Dict[str, Any]] = event.items
total: float = event.total_tt_value
```
### 6. Follow Naming Conventions
```python
# ✅ Good
class LootTrackerPlugin(BasePlugin):
def on_loot_received(self):
pass
# ❌ Avoid
class lootTracker(BasePlugin):
def loot(self):
pass
```
### 7. Document Your Plugin
```python
class MyPlugin(BasePlugin):
"""
Brief description of what this plugin does.
Features:
- Feature 1
- Feature 2
Usage:
1. Step 1
2. Step 2
Hotkeys:
- Ctrl+Shift+Y: Toggle plugin
"""
```
---
## Error Handling
All APIs provide specific exceptions:
```python
from core.api import (
PluginAPIError,
ServiceNotAvailableError,
ExternalAPIError
)
try:
text = api.recognize_text((0, 0, 100, 100))
except ServiceNotAvailableError:
print("OCR not available")
except PluginAPIError as e:
print(f"API error: {e}")
```
---
## See Also
- [Plugin Development Guide](./docs/PLUGIN_DEVELOPMENT.md) - Detailed plugin tutorial
- [Architecture Overview](./ARCHITECTURE.md) - System architecture
- [Nexus API Reference](./docs/NEXUS_API_REFERENCE.md) - Entropia Nexus API
- [Contributing](./CONTRIBUTING.md) - How to contribute
Reference in New Issue View Git Blame Copy Permalink