first commit
This commit is contained in:
Beyhan Oğur
+459
@@ -0,0 +1,459 @@
|
||||
# Agent Architecture & Base Classes
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
|
||||
## Introduction
|
||||
This document explains the agent framework architecture used by ClassicAssist.Avalonia. It focuses on base manager classes, agent lifecycle management, registration and discovery patterns, event handling, state management, integration with the game engine, network packet processing, and rule evaluation for condition matching and action execution. It also covers threading models, performance considerations, memory management for long-running agents, and practical guidance for extending base classes and implementing custom agent logic.
|
||||
|
||||
## Project Structure
|
||||
The agent framework spans shared networking, data managers, UI integration, and platform dispatchers:
|
||||
- Shared core provides the engine entry point, packet handlers, queues, and manager abstractions.
|
||||
- Avalonia-specific code integrates UI threads and dispatcher invokers.
|
||||
- Managers implement concrete agent behaviors (e.g., autoloot, dress, scavenger, vendor buy/sell).
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Core"
|
||||
Engine["Engine"]
|
||||
InPktHdlrs["IncomingPacketHandlers"]
|
||||
OutPktHdlrs["OutgoingPacketHandlers"]
|
||||
PktHandler["PacketHandler"]
|
||||
InPktFilters["IncomingPacketFilters"]
|
||||
ActionQ["ActionPacketQueue"]
|
||||
TQ["ThreadQueue"]
|
||||
TPQ["ThreadPriorityQueue"]
|
||||
MacroMgr["MacroManager"]
|
||||
HotkeyMgr["HotkeyManager"]
|
||||
AutolootMgr["AutolootManager"]
|
||||
DressMgr["DressManager"]
|
||||
ScavengerMgr["ScavengerManager"]
|
||||
VendorBuy["VendorBuyAgentEntry"]
|
||||
VendorSell["VendorSellAgentEntry"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
AgentsTab["AgentsTabControl"]
|
||||
Dispatcher["AvaloniaDispatcher"]
|
||||
UIInvoker["AvaloniaUIInvoker"]
|
||||
end
|
||||
Engine --> InPktHdlrs
|
||||
Engine --> OutPktHdlrs
|
||||
InPktHdlrs --> PktHandler
|
||||
OutPktHdlrs --> PktHandler
|
||||
InPktHdlrs --> InPktFilters
|
||||
InPktHdlrs --> ActionQ
|
||||
ActionQ --> TQ
|
||||
ActionQ --> TPQ
|
||||
MacroMgr --> Engine
|
||||
HotkeyMgr --> Engine
|
||||
AutolootMgr --> Engine
|
||||
DressMgr --> Engine
|
||||
ScavengerMgr --> Engine
|
||||
VendorBuy --> Engine
|
||||
VendorSell --> Engine
|
||||
AgentsTab --> Dispatcher
|
||||
Dispatcher --> UIInvoker
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Core Components
|
||||
- Engine: Central orchestrator that initializes subsystems, wires up packet handlers, and coordinates managers.
|
||||
- Packet Handlers: Incoming and outgoing packet routing to registered handlers and filters.
|
||||
- Queues: Thread-safe queues for deferring actions across threads.
|
||||
- Managers: Feature-specific agents (autoloot, dress, scavenger, vendor buy/sell) that encapsulate rules and state.
|
||||
- UI Integration: Avalonia dispatcher and UI invoker bridge background work to UI safely.
|
||||
|
||||
Key responsibilities:
|
||||
- Registration and discovery of packet handlers and managers.
|
||||
- Event-driven updates from packets and timers.
|
||||
- Rule evaluation pipelines for conditions and actions.
|
||||
- Threading model ensuring safe cross-thread operations.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The agent framework follows an event-driven architecture:
|
||||
- The game engine receives network packets and routes them through incoming/outgoing handlers.
|
||||
- Filters can inspect or block packets before they reach handlers.
|
||||
- Handlers update shared state and enqueue actions via thread-safe queues.
|
||||
- Managers subscribe to events and process queued actions, applying rules and performing actions.
|
||||
- UI components observe state changes and are updated via the Avalonia dispatcher.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "Game Engine"
|
||||
participant InPkt as "IncomingPacketHandlers"
|
||||
participant Filter as "IncomingPacketFilters"
|
||||
participant Handler as "PacketHandler"
|
||||
participant Queue as "ActionPacketQueue"
|
||||
participant Manager as "Agent Manager"
|
||||
participant UI as "AvaloniaDispatcher/UIInvoker"
|
||||
Game->>InPkt : "Receive packet"
|
||||
InPkt->>Filter : "Apply filters"
|
||||
Filter-->>InPkt : "Allow/Deny"
|
||||
InPkt->>Handler : "Dispatch to handler"
|
||||
Handler->>Manager : "Update state / raise events"
|
||||
Handler->>Queue : "Enqueue action"
|
||||
Queue-->>Manager : "Dequeue and execute"
|
||||
Manager->>UI : "Invoke UI updates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Base Manager Pattern and Lifecycle
|
||||
Managers encapsulate agent behavior and configuration. Typical lifecycle:
|
||||
- Initialization: Register handlers, load configuration, initialize state.
|
||||
- Runtime: Subscribe to engine events, evaluate rules, perform actions.
|
||||
- Cleanup: Unsubscribe, release resources, persist state.
|
||||
|
||||
Common patterns:
|
||||
- Configuration entries per agent type (e.g., vendor buy/sell entries).
|
||||
- State held in collections and caches for fast lookup.
|
||||
- Event-driven updates triggered by packet handlers or timers.
|
||||
|
||||
Examples:
|
||||
- Autoloot manager maintains lists of constraints and properties to match items.
|
||||
- Dress manager tracks desired equipment sets and applies them based on conditions.
|
||||
- Scavenger manager defines loot priorities and filtering rules.
|
||||
- Vendor buy/sell managers manage shop lists and transaction logic.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### Agent Registration System
|
||||
Registration typically occurs during engine initialization:
|
||||
- Managers register themselves with the engine.
|
||||
- Packet handlers are discovered and bound to specific packet types.
|
||||
- UI tabs bind to manager view models for display and control.
|
||||
|
||||
Patterns:
|
||||
- Centralized registry in the engine.
|
||||
- Attribute-based or convention-based discovery for handlers and commands.
|
||||
- Tabbed UI surfaces each agent’s configuration and status.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
|
||||
|
||||
### Event Handling Mechanisms
|
||||
Event flow:
|
||||
- Network packets arrive and are filtered.
|
||||
- Handlers update shared state and raise domain events.
|
||||
- Managers listen to these events and react accordingly.
|
||||
- Actions may be enqueued for asynchronous execution.
|
||||
|
||||
Best practices:
|
||||
- Keep handlers lightweight; offload heavy work to queues.
|
||||
- Use immutable snapshots where possible to reduce contention.
|
||||
- Ensure thread safety when updating shared collections.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
|
||||
### State Management Patterns
|
||||
State is managed centrally and accessed by multiple managers:
|
||||
- Entity collections and caches provide fast lookups.
|
||||
- Managers maintain local state derived from global state.
|
||||
- Changes are propagated via events and queues.
|
||||
|
||||
Guidelines:
|
||||
- Prefer read-only views for UI-bound data.
|
||||
- Batch updates to minimize churn.
|
||||
- Persist configuration separately from runtime state.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### Network Packet Integration
|
||||
Integration points:
|
||||
- IncomingPacketHandlers route packets to specific handlers.
|
||||
- IncomingPacketFilters allow pre-processing and blocking.
|
||||
- OutgoingPacketHandlers intercept outgoing actions for logging or modification.
|
||||
- PacketHandler centralizes dispatch logic.
|
||||
|
||||
Considerations:
|
||||
- Avoid blocking in handlers; use queues for deferred work.
|
||||
- Validate packet payloads before processing.
|
||||
- Maintain compatibility across client/server protocol versions.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PacketHandler.cs](file://ClassicAssist.Shared/UO/Network/PacketHandler.cs)
|
||||
|
||||
### Rule Evaluation System: Conditions and Actions
|
||||
Rule evaluation pipeline:
|
||||
- Collect candidate entities or events.
|
||||
- Apply filter conditions (e.g., item properties, light level, cliloc text).
|
||||
- Compute priority or score.
|
||||
- Execute actions (e.g., pick up, equip, sell/buy).
|
||||
|
||||
Flowchart:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Rule Evaluation"]) --> Gather["Gather Candidates"]
|
||||
Gather --> ApplyFilters["Apply Filter Conditions"]
|
||||
ApplyFilters --> Matched{"Any Matches?"}
|
||||
Matched --> |No| End(["End"])
|
||||
Matched --> |Yes| Score["Compute Priority/Score"]
|
||||
Score --> SelectTop["Select Top Candidate(s)"]
|
||||
SelectTop --> ExecuteActions["Execute Actions"]
|
||||
ExecuteActions --> UpdateState["Update State"]
|
||||
UpdateState --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### Extending Base Classes and Implementing Custom Logic
|
||||
To extend the framework:
|
||||
- Create a new manager class following existing patterns.
|
||||
- Initialize configuration entries and subscribe to relevant events.
|
||||
- Implement rule evaluation methods and action execution.
|
||||
- Integrate with UI via a tab control if needed.
|
||||
|
||||
Example references:
|
||||
- Autoloot manager demonstrates property-based filtering and selection.
|
||||
- Dress manager shows conditional application of equipment sets.
|
||||
- Vendor buy/sell entries define structured configurations for transactions.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### Managing Agent Configuration
|
||||
Configuration is typically stored in structured entries:
|
||||
- Each agent has dedicated entry types (e.g., vendor buy/sell entries).
|
||||
- Managers load and apply configurations at startup.
|
||||
- UI exposes configuration editors bound to view models.
|
||||
|
||||
Recommendations:
|
||||
- Validate configuration on load.
|
||||
- Provide defaults for missing fields.
|
||||
- Persist changes atomically to avoid corruption.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/AgentsTabControl.axaml.cs)
|
||||
|
||||
### Threading Models and Cross-Thread Operations
|
||||
Threading model:
|
||||
- Packet processing runs on network threads.
|
||||
- Managers may run on background threads.
|
||||
- UI updates must be marshaled to the UI thread using the dispatcher.
|
||||
|
||||
Queues:
|
||||
- ActionPacketQueue provides a unified queue for actions.
|
||||
- ThreadQueue and ThreadPriorityQueue support prioritized scheduling.
|
||||
|
||||
Cross-thread best practices:
|
||||
- Enqueue work instead of direct UI calls.
|
||||
- Use the Avalonia dispatcher to marshal UI updates.
|
||||
- Avoid long-running operations on UI threads.
|
||||
|
||||
**Section sources**
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
### Performance Considerations
|
||||
- Minimize allocations in hot paths (packet handlers, rule evaluation).
|
||||
- Use efficient data structures for entity lookups and filtering.
|
||||
- Batch UI updates to reduce redraw overhead.
|
||||
- Leverage priority queues for time-sensitive actions.
|
||||
- Profile memory usage for long-running sessions and clear caches when appropriate.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Memory Management for Long-Running Agents
|
||||
- Release subscriptions and timers on cleanup.
|
||||
- Avoid retaining large object graphs in static caches.
|
||||
- Periodically compact or rebuild indexes if necessary.
|
||||
- Monitor GC pressure and adjust batching strategies.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies among core components:
|
||||
- Engine depends on packet handlers and managers.
|
||||
- Packet handlers depend on filters and queues.
|
||||
- Managers depend on shared data and configuration entries.
|
||||
- UI depends on dispatcher and invoker for cross-thread updates.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Engine --> InPktHdlrs
|
||||
Engine --> OutPktHdlrs
|
||||
InPktHdlrs --> InPktFilters
|
||||
InPktHdlrs --> ActionQ
|
||||
ActionQ --> TQ
|
||||
ActionQ --> TPQ
|
||||
Managers["Managers (Autoloot, Dress, Scavenger, Vendor)"] --> Engine
|
||||
UI["Avalonia UI"] --> Dispatcher
|
||||
Dispatcher --> UIInvoker
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Favor lightweight handlers and defer heavy computations to queues.
|
||||
- Use efficient filtering and early exits in rule evaluation.
|
||||
- Reduce UI churn by batching updates and avoiding frequent rebinds.
|
||||
- Monitor queue depths and backpressure to prevent memory growth.
|
||||
- Profile critical paths under realistic loads to identify bottlenecks.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Packets not processed: Verify filters are not blocking; check handler registrations.
|
||||
- UI not updating: Ensure actions are dispatched via Avalonia dispatcher.
|
||||
- High CPU usage: Inspect tight loops in rule evaluation; add throttling or batching.
|
||||
- Memory leaks: Confirm unsubscription from events and disposal of timers.
|
||||
|
||||
Diagnostic utilities:
|
||||
- Logging in packet handlers and managers.
|
||||
- Queue depth monitoring.
|
||||
- UI thread invocation failures captured by dispatcher.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Conclusion
|
||||
The ClassicAssist.Avalonia agent framework is built around a robust event-driven architecture with clear separation between networking, rule evaluation, and UI concerns. Managers encapsulate agent logic and configuration, while queues and dispatchers ensure safe, performant operation across threads. By following the patterns outlined here—registration, event handling, rule evaluation, and cross-thread updates—you can extend the system with custom agents that integrate seamlessly with the game engine and UI.
|
||||
@@ -0,0 +1,445 @@
|
||||
# Agent Framework
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
|
||||
The ClassicAssist.Avalonia agent framework provides a sophisticated automation system for Ultima Online gameplay through a modular agent architecture. This framework enables players to create intelligent agents that can automatically perform various tasks such as loot collection, equipment management, item scavenging, and vendor operations. The framework is built around a rule-based engine that evaluates conditions and executes actions based on game state and player-defined rules.
|
||||
|
||||
The agent system follows a manager-based pattern where each type of automated behavior is encapsulated in its own manager class, providing clear separation of concerns and making it easy to extend functionality with custom agents.
|
||||
|
||||
## Project Structure
|
||||
|
||||
The agent framework is primarily implemented within the ClassicAssist.Shared project, with UI components distributed across both ClassicAssist (WPF) and ClassicAssist.Avalonia projects. The core architecture consists of:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Agent Framework Core"
|
||||
Engine[Engine]
|
||||
ManagerBase[Manager Base Class]
|
||||
RuleEngine[Rule Engine]
|
||||
ConditionEvaluator[Condition Evaluator]
|
||||
ActionExecutor[Action Executor]
|
||||
end
|
||||
subgraph "Built-in Agents"
|
||||
Autoloot[AUTOLootManager]
|
||||
Dress[DressManager]
|
||||
Scavenger[ScavengerManager]
|
||||
VendorBuy[VendorBuyManager]
|
||||
VendorSell[VendorSellManager]
|
||||
Organizer[OrganizerManager]
|
||||
end
|
||||
subgraph "Data Models"
|
||||
EntryModels[Entry Models]
|
||||
PropertySystem[Property System]
|
||||
FilterSystem[Filter System]
|
||||
end
|
||||
subgraph "UI Layer"
|
||||
WPFUI[WPF UI]
|
||||
AvaloniaUI[Avalonia UI]
|
||||
ViewModels[ViewModels]
|
||||
end
|
||||
Engine --> ManagerBase
|
||||
ManagerBase --> RuleEngine
|
||||
RuleEngine --> ConditionEvaluator
|
||||
RuleEngine --> ActionExecutor
|
||||
Autoloot --> ManagerBase
|
||||
Dress --> ManagerBase
|
||||
Scavenger --> ManagerBase
|
||||
ManagerBase --> EntryModels
|
||||
EntryModels --> PropertySystem
|
||||
EntryModels --> FilterSystem
|
||||
WPFUI --> ViewModels
|
||||
AvaloniaUI --> ViewModels
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
## Core Components
|
||||
|
||||
### Agent Architecture Pattern
|
||||
|
||||
The agent framework implements a manager-based architecture where each specialized agent type extends a common base class. This pattern provides:
|
||||
|
||||
- **Lifecycle Management**: Standardized initialization, update, and cleanup processes
|
||||
- **Event Handling**: Consistent event processing and response mechanisms
|
||||
- **Configuration Management**: Unified approach to loading, saving, and validating agent configurations
|
||||
- **State Management**: Centralized state tracking and persistence
|
||||
- **Threading Support**: Built-in support for asynchronous operations and thread safety
|
||||
|
||||
### Base Classes and Inheritance Hierarchy
|
||||
|
||||
The framework establishes a clear inheritance hierarchy that promotes code reuse and consistency:
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentBase {
|
||||
+string Name
|
||||
+bool IsEnabled
|
||||
+DateTime LastUpdated
|
||||
+void Initialize()
|
||||
+void Update()
|
||||
+void Cleanup()
|
||||
+void LoadConfiguration()
|
||||
+void SaveConfiguration()
|
||||
+event EventHandler OnStateChanged
|
||||
}
|
||||
class ManagerBase {
|
||||
+T[] Entries
|
||||
+Dictionary~string, object~ Properties
|
||||
+void AddEntry(T entry)
|
||||
+void RemoveEntry(string id)
|
||||
+T GetEntry(string id)
|
||||
+void ProcessEntries()
|
||||
+void ValidateEntries()
|
||||
}
|
||||
class AutolootManager {
|
||||
+AutolootEntry[] Rules
|
||||
+void EvaluateLootConditions()
|
||||
+void ExecuteLootActions()
|
||||
+void HandleItemDrop()
|
||||
}
|
||||
class DressManager {
|
||||
+DressAgentEntry[] Outfits
|
||||
+void EvaluateOutfitRules()
|
||||
+void EquipItems()
|
||||
+void UnequipItems()
|
||||
}
|
||||
class ScavengerManager {
|
||||
+ScavengerEntry[] ScavengeRules
|
||||
+void FindScavengeTargets()
|
||||
+void MoveToTarget()
|
||||
+void PickUpItems()
|
||||
}
|
||||
AgentBase <|-- ManagerBase
|
||||
ManagerBase <|-- AutolootManager
|
||||
ManagerBase <|-- DressManager
|
||||
ManagerBase <|-- ScavengerManager
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### Rule Engine Integration
|
||||
|
||||
The rule engine serves as the core decision-making component, evaluating conditions and executing appropriate actions. It supports:
|
||||
|
||||
- **Complex Condition Evaluation**: Boolean logic with AND, OR, NOT operators
|
||||
- **Property Matching**: Dynamic property comparison using wildcards and regular expressions
|
||||
- **Context-Aware Conditions**: Access to game state, player status, and environmental factors
|
||||
- **Priority-Based Execution**: Ordered evaluation of multiple rules with conflict resolution
|
||||
|
||||
### Data Model Architecture
|
||||
|
||||
Each agent type defines its own entry models that specify the configuration and behavior parameters:
|
||||
|
||||
| Agent Type | Entry Model | Key Properties | Purpose |
|
||||
|------------|-------------|----------------|---------|
|
||||
| Autoloot | AutolootEntry | ItemCriteria, Actions, Priority | Define what items to collect and how to handle them |
|
||||
| Dress | DressAgentEntry | OutfitName, Items, Conditions | Specify equipment combinations and activation rules |
|
||||
| Scavenger | ScavengerEntry | TargetTypes, PickupRange, Actions | Configure automatic item gathering behavior |
|
||||
|
||||
**Section sources**
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The agent framework follows a layered architecture that separates concerns and promotes maintainability:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "Game Engine"
|
||||
participant EventSystem as "Event System"
|
||||
participant AgentManager as "Agent Manager"
|
||||
participant RuleEngine as "Rule Engine"
|
||||
participant Agent as "Specific Agent"
|
||||
participant ActionQueue as "Action Queue"
|
||||
participant GameClient as "Game Client"
|
||||
Game->>EventSystem : Game Event
|
||||
EventSystem->>AgentManager : Dispatch Event
|
||||
AgentManager->>RuleEngine : Evaluate Conditions
|
||||
RuleEngine->>Agent : Check Agent Rules
|
||||
Agent->>Agent : Process Logic
|
||||
Agent->>ActionQueue : Queue Actions
|
||||
ActionQueue->>GameClient : Execute Actions
|
||||
GameClient-->>Game : Send Commands
|
||||
Note over Agent,ActionQueue : Asynchronous action processing
|
||||
Note over RuleEngine,Agent : Thread-safe condition evaluation
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### AutolootManager Analysis
|
||||
|
||||
The AutolootManager handles automatic item collection based on configurable rules. It processes incoming item drop events and determines whether items should be picked up based on defined criteria.
|
||||
|
||||
#### Key Features:
|
||||
- **Multi-Criteria Matching**: Supports matching by name, hue, weight, value, and custom properties
|
||||
- **Smart Filtering**: Advanced filtering with regex support and property-based conditions
|
||||
- **Action Queuing**: Intelligent queuing of pickup actions to prevent conflicts
|
||||
- **Priority System**: Multiple rules can match an item, with priority determining which action takes precedence
|
||||
|
||||
#### Implementation Pattern:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Item Drop Event]) --> ParseItem["Parse Item Properties"]
|
||||
ParseItem --> LoadRules["Load Active Autoloot Rules"]
|
||||
LoadRules --> EvaluateRules["Evaluate Each Rule"]
|
||||
EvaluateRules --> MatchFound{"Any Rule Matches?"}
|
||||
MatchFound --> |No| IgnoreItem["Ignore Item"]
|
||||
MatchFound --> |Yes| DetermineAction["Determine Best Action"]
|
||||
DetermineAction --> QueueAction["Queue Pickup Action"]
|
||||
QueueAction --> End([Process Complete])
|
||||
IgnoreItem --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
|
||||
### DressManager Analysis
|
||||
|
||||
The DressManager automates equipment changes based on situational awareness and predefined outfit configurations. It monitors game state and automatically equips or unequips items to optimize character performance.
|
||||
|
||||
#### Core Functionality:
|
||||
- **Outfit Management**: Create and manage multiple outfit configurations
|
||||
- **Conditional Activation**: Activate outfits based on combat mode, location, or other game states
|
||||
- **Inventory Awareness**: Understand current inventory and equipped items
|
||||
- **Conflict Resolution**: Handle situations where required items are not available
|
||||
|
||||
#### State Machine:
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Monitoring : "Start Agent"
|
||||
Monitoring --> ConditionCheck : "Periodic Check"
|
||||
ConditionCheck --> NeedsChange{"Outfit Change Needed?"}
|
||||
NeedsChange --> |No| Monitoring
|
||||
NeedsChange --> |Yes| PrepareChange["Prepare Item Changes"]
|
||||
PrepareChange --> HasItems{"All Items Available?"}
|
||||
HasItems --> |No| LogError["Log Missing Items"]
|
||||
HasItems --> |Yes| ExecuteChange["Execute Equipment Change"]
|
||||
ExecuteChange --> VerifyChange["Verify New Outfit"]
|
||||
VerifyChange --> Monitoring
|
||||
LogError --> Monitoring
|
||||
Monitoring --> [*] : "Stop Agent"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
|
||||
### ScavengerManager Analysis
|
||||
|
||||
The ScavengerManager provides automatic item collection capabilities, allowing characters to gather specific types of items from the ground without manual intervention.
|
||||
|
||||
#### Advanced Features:
|
||||
- **Pathfinding Integration**: Intelligent movement to target locations
|
||||
- **Range Management**: Respects pickup range limitations and pathfinding obstacles
|
||||
- **Batch Processing**: Efficiently handles multiple items in close proximity
|
||||
- **Safety Checks**: Avoids dangerous areas and respects game mechanics
|
||||
|
||||
#### Processing Pipeline:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
ScanArea["Scan Area for Items"] --> FilterItems["Filter by Criteria"]
|
||||
FilterItems --> Prioritize["Prioritize Targets"]
|
||||
Prioritize --> Pathfind["Calculate Path to Target"]
|
||||
Pathfind --> CanReach{"Can Reach Target?"}
|
||||
CanReach --> |No| SkipTarget["Skip and Try Next"]
|
||||
CanReach --> |Yes| MoveToTarget["Move to Target Location"]
|
||||
MoveToTarget --> PickUpItem["Pick Up Item"]
|
||||
PickUpItem --> InventoryCheck{"Inventory Full?"}
|
||||
InventoryCheck --> |Yes| ReturnHome["Return to Home Location"]
|
||||
InventoryCheck --> |No| ContinueScavenging["Continue Scavenging"]
|
||||
SkipTarget --> ContinueScavenging
|
||||
ReturnHome --> ScanArea
|
||||
ContinueScavenging --> ScanArea
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
|
||||
The agent framework maintains loose coupling between components while ensuring proper data flow and event handling:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Core Dependencies"
|
||||
Engine[Engine]
|
||||
Network[Network Layer]
|
||||
Objects[Object System]
|
||||
Filters[Filter System]
|
||||
end
|
||||
subgraph "Agent Managers"
|
||||
AutoLoot[AUTOLootManager]
|
||||
Dress[DressManager]
|
||||
Scavenger[ScavengerManager]
|
||||
end
|
||||
subgraph "External Systems"
|
||||
GameAPI[Game API]
|
||||
Storage[Storage System]
|
||||
UI[UI System]
|
||||
end
|
||||
Engine --> AutoLoot
|
||||
Engine --> Dress
|
||||
Engine --> Scavenger
|
||||
AutoLoot --> Objects
|
||||
Dress --> Objects
|
||||
Scavenger --> Objects
|
||||
AutoLoot --> Filters
|
||||
Dress --> Filters
|
||||
Scavenger --> Filters
|
||||
AutoLoot --> Network
|
||||
Dress --> Network
|
||||
Scavenger --> Network
|
||||
AutoLoot --> Storage
|
||||
Dress --> Storage
|
||||
Scavenger --> Storage
|
||||
AutoLoot --> UI
|
||||
Dress --> UI
|
||||
Scavenger --> UI
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Threading Model
|
||||
|
||||
The agent framework implements a multi-threaded architecture designed for optimal performance:
|
||||
|
||||
- **Main Thread**: UI updates and critical game interactions
|
||||
- **Worker Threads**: Rule evaluation and complex calculations
|
||||
- **Background Tasks**: File I/O and network operations
|
||||
- **Thread-Safe Collections**: All shared data structures use concurrent collections
|
||||
|
||||
### Memory Management
|
||||
|
||||
Key memory optimization strategies include:
|
||||
|
||||
- **Object Pooling**: Reuse frequently created objects to reduce GC pressure
|
||||
- **Lazy Loading**: Load agent configurations only when needed
|
||||
- **Event Unsubscription**: Proper cleanup of event handlers to prevent memory leaks
|
||||
- **Weak References**: Use weak references for long-lived observers
|
||||
|
||||
### Optimization Techniques
|
||||
|
||||
1. **Caching**: Cache frequently accessed game data and rule evaluations
|
||||
2. **Batch Processing**: Group similar operations to minimize overhead
|
||||
3. **Early Exit**: Short-circuit expensive operations when possible
|
||||
4. **Asynchronous Operations**: Non-blocking I/O and network calls
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
**Agent Not Starting:**
|
||||
- Verify agent configuration syntax
|
||||
- Check for missing dependencies or invalid property values
|
||||
- Review error logs for initialization failures
|
||||
|
||||
**Poor Performance:**
|
||||
- Reduce number of active rules per agent
|
||||
- Optimize condition complexity and avoid expensive operations
|
||||
- Monitor memory usage and garbage collection frequency
|
||||
|
||||
**Incorrect Behavior:**
|
||||
- Enable debug logging for detailed operation traces
|
||||
- Test individual rules in isolation
|
||||
- Verify game state assumptions in conditions
|
||||
|
||||
### Debugging Tools
|
||||
|
||||
The framework provides comprehensive debugging capabilities:
|
||||
|
||||
- **Live Rule Evaluation**: Real-time testing of condition logic
|
||||
- **Performance Profiling**: Identify bottlenecks in rule processing
|
||||
- **State Inspection**: Examine agent internal state and variables
|
||||
- **Event Tracing**: Track game events and agent responses
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
|
||||
## Conclusion
|
||||
|
||||
The ClassicAssist.Avalonia agent framework provides a robust, extensible foundation for creating intelligent automation agents. Its manager-based architecture, combined with a powerful rule engine and comprehensive threading model, enables developers to create sophisticated agents that can handle complex gameplay scenarios efficiently.
|
||||
|
||||
The framework's design emphasizes modularity, performance, and ease of extension, making it suitable for both simple automation tasks and complex AI behaviors. By following the established patterns and leveraging the built-in utilities, developers can create reliable agents that enhance the Ultima Online gaming experience.
|
||||
|
||||
## Appendices
|
||||
|
||||
### Creating Custom Agents
|
||||
|
||||
To implement a custom agent:
|
||||
|
||||
1. **Extend the Base Manager Class**: Create a new class inheriting from the appropriate base manager
|
||||
2. **Define Entry Models**: Create configuration classes for your agent's rules
|
||||
3. **Implement Lifecycle Methods**: Override initialization, update, and cleanup methods
|
||||
4. **Register Event Handlers**: Subscribe to relevant game events
|
||||
5. **Add Configuration Support**: Implement save/load functionality for your rules
|
||||
6. **Create UI Components**: Build user interfaces for configuring your agent
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Keep Rules Simple**: Break complex logic into smaller, testable components
|
||||
- **Handle Errors Gracefully**: Always validate inputs and handle exceptions
|
||||
- **Use Appropriate Threading**: Keep UI operations on the main thread
|
||||
- **Monitor Performance**: Profile regularly and optimize hot paths
|
||||
- **Document Your Rules**: Provide clear descriptions for complex conditions
|
||||
@@ -0,0 +1,446 @@
|
||||
# Autoloot Agent
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
|
||||
- [AutolootTabControl.xaml](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml)
|
||||
- [ClilocSelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/ClilocSelectionWindow.xaml)
|
||||
- [CustomPropertiesWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/CustomPropertiesWindow.xaml)
|
||||
- [PropertySelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/PropertySelectionWindow.xaml)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [CustomPropertiesViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/CustomPropertiesViewModel.cs)
|
||||
- [PropertySelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/PropertySelectionViewModel.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
The Autoloot agent automatically picks up items based on user-defined rules and conditions. It evaluates incoming or existing items against a set of constraints, resolves conflicts when multiple rules match, and executes pickup actions through the game client’s targeting system. The feature includes a rule creation interface with property matching, operator-based comparisons, logical grouping, and testing utilities to validate rules before enabling them.
|
||||
|
||||
## Project Structure
|
||||
The Autoloot system is implemented across shared data models, UI views/view models, and network integration points:
|
||||
- Data layer: rule definitions, operators, properties, helpers, and manager orchestration
|
||||
- UI layer (Avalonia): tabs and windows for rule management and testing
|
||||
- Integration: item objects and packet handlers that trigger autoloot evaluation
|
||||
- Tests: unit tests validating core logic
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Data Layer"
|
||||
M["AutolootManager"]
|
||||
E["AutolootEntry"]
|
||||
C["AutolootConstraintEntry"]
|
||||
O["AutolootOperator"]
|
||||
P["PropertyEntry / PropertyType"]
|
||||
H["AutolootHelpers"]
|
||||
end
|
||||
subgraph "UI Layer (Avalonia)"
|
||||
T["AutolootTabControl"]
|
||||
VM["AutolootViewModel"]
|
||||
W1["ClilocSelectionWindow"]
|
||||
W2["CustomPropertiesWindow"]
|
||||
W3["PropertySelectionWindow"]
|
||||
VM1["ClilocSelectionViewModel"]
|
||||
VM2["CustomPropertiesViewModel"]
|
||||
VM3["PropertySelectionViewModel"]
|
||||
end
|
||||
subgraph "Integration"
|
||||
I["Item"]
|
||||
PH["IncomingPacketHandlers"]
|
||||
CCP["ContainerContentsPacket"]
|
||||
DI["DropItem"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
AT["AutolootTests"]
|
||||
end
|
||||
VM --> M
|
||||
T --> VM
|
||||
W1 --> VM1
|
||||
W2 --> VM2
|
||||
W3 --> VM3
|
||||
M --> E
|
||||
E --> C
|
||||
C --> O
|
||||
C --> P
|
||||
M --> H
|
||||
PH --> CCP
|
||||
PH --> DI
|
||||
CCP --> M
|
||||
DI --> M
|
||||
I --> M
|
||||
AT --> M
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/ClilocSelectionWindow.xaml)
|
||||
- [CustomPropertiesWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/CustomPropertiesWindow.xaml)
|
||||
- [PropertySelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/PropertySelectionWindow.xaml)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
- [CustomPropertiesViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/CustomPropertiesViewModel.cs)
|
||||
- [PropertySelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/PropertySelectionViewModel.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
|
||||
## Core Components
|
||||
- AutolootManager: Central orchestrator that loads, evaluates, and applies autoloot rules. It integrates with item events and packet handlers to decide whether to pick up an item.
|
||||
- AutolootEntry: Represents a single autoloot rule with metadata, enabled state, and associated constraints.
|
||||
- AutolootConstraintEntry: Encapsulates a condition composed of a property, operator, and value(s). Constraints are combined using logical operators within a rule.
|
||||
- AutolootOperator: Enumerates supported comparison operators used by constraints (e.g., equals, contains, greater than).
|
||||
- PropertyEntry and PropertyType: Define available item properties and their types for matching.
|
||||
- AutolootHelpers: Utility functions for normalization, parsing, and common operations used during evaluation.
|
||||
- AutolootViewModel: View model backing the Avalonia tab; exposes commands for creating, editing, testing, and bulk-managing rules.
|
||||
- UI Windows: Cliloc selection, custom properties, and property selection dialogs assist users in building complex rules.
|
||||
|
||||
Key responsibilities:
|
||||
- Rule lifecycle: create, edit, enable/disable, delete, import/export
|
||||
- Constraint evaluation: property extraction, type conversion, operator application, logical combination
|
||||
- Conflict resolution: priority ordering and first-match semantics
|
||||
- Testing: dry-run evaluation against sample items without performing pickups
|
||||
- Integration: subscribe to item arrival events and container updates
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/ClilocSelectionWindow.xaml)
|
||||
- [CustomPropertiesWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/CustomPropertiesWindow.xaml)
|
||||
- [PropertySelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/PropertySelectionWindow.xaml)
|
||||
|
||||
## Architecture Overview
|
||||
The autoloot pipeline subscribes to item-related events and packet handlers. When an item becomes available (dropped or revealed in containers), the manager evaluates it against all active rules. Each rule consists of one or more constraints evaluated with logical operators. If a rule matches, the manager selects the highest-priority rule and triggers a pickup action via the targeting subsystem.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "Game Client"
|
||||
participant Net as "IncomingPacketHandlers"
|
||||
participant Item as "Item"
|
||||
participant Manager as "AutolootManager"
|
||||
participant Rule as "AutolootEntry"
|
||||
participant C as "AutolootConstraintEntry"
|
||||
participant Target as "Targeting System"
|
||||
Game->>Net : "DropItem / ContainerContentsPacket"
|
||||
Net->>Manager : "Notify item event"
|
||||
Manager->>Item : "Read properties"
|
||||
loop For each active rule
|
||||
Manager->>Rule : "Evaluate(rule)"
|
||||
Rule->>C : "Evaluate constraint"
|
||||
C-->>Rule : "Boolean result"
|
||||
Rule-->>Manager : "Matched?"
|
||||
end
|
||||
alt "Multiple matches"
|
||||
Manager->>Manager : "Resolve conflict by priority"
|
||||
end
|
||||
alt "Highest priority matched"
|
||||
Manager->>Target : "Pickup(item)"
|
||||
Target-->>Game : "Pickup command"
|
||||
else "No match"
|
||||
Manager-->>Game : "Ignore"
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Rule Model and Evaluation Engine
|
||||
- AutolootEntry holds rule metadata and a list of constraints. Rules can be enabled/disabled and have a priority field to resolve conflicts.
|
||||
- AutolootConstraintEntry defines a property selector, operator, and value(s). Logical combination within a rule uses AND/OR grouping.
|
||||
- AutolootOperator enumerates supported comparisons.
|
||||
- PropertyEntry and PropertyType define the schema of item attributes available for matching.
|
||||
- AutolootHelpers provides normalization and parsing utilities used during evaluation.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AutolootManager {
|
||||
+LoadRules()
|
||||
+Evaluate(item) bool
|
||||
+Pickup(item) void
|
||||
+ResolveConflicts(matches) AutolootEntry
|
||||
}
|
||||
class AutolootEntry {
|
||||
+string name
|
||||
+bool enabled
|
||||
+int priority
|
||||
+AutolootConstraintEntry[] constraints
|
||||
+Matches(item) bool
|
||||
}
|
||||
class AutolootConstraintEntry {
|
||||
+PropertyEntry property
|
||||
+AutolootOperator op
|
||||
+object value
|
||||
+Evaluate(propertyValue) bool
|
||||
}
|
||||
class AutolootOperator {
|
||||
<<enum>>
|
||||
}
|
||||
class PropertyEntry {
|
||||
+string name
|
||||
+PropertyType type
|
||||
}
|
||||
class PropertyType {
|
||||
<<enum>>
|
||||
}
|
||||
class AutolootHelpers {
|
||||
+Normalize(text) string
|
||||
+Parse(value, type) object
|
||||
}
|
||||
AutolootManager --> AutolootEntry : "manages"
|
||||
AutolootEntry --> AutolootConstraintEntry : "contains"
|
||||
AutolootConstraintEntry --> PropertyEntry : "uses"
|
||||
AutolootConstraintEntry --> AutolootOperator : "applies"
|
||||
AutolootManager --> AutolootHelpers : "uses"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
|
||||
### Rule Creation Interface and Property Matching
|
||||
- AutolootTabControl hosts the main rule editor UI.
|
||||
- AutolootViewModel exposes commands for adding/removing rules, toggling enabled state, setting priorities, and running tests.
|
||||
- PropertySelectionWindow and PropertySelectionViewModel help choose from available properties and types.
|
||||
- CustomPropertiesWindow and CustomPropertiesViewModel allow defining or selecting custom properties for advanced matching.
|
||||
- ClilocSelectionWindow and ClilocSelectionViewModel provide localized text selection for cliloc-based matching.
|
||||
|
||||
Typical workflow:
|
||||
1. Open the Autoloot tab.
|
||||
2. Create a new rule and assign a descriptive name.
|
||||
3. Add constraints by selecting a property, operator, and value.
|
||||
4. Use logical grouping to combine constraints (AND/OR).
|
||||
5. Test the rule against sample items using the test function.
|
||||
6. Save and enable the rule.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [PropertySelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/PropertySelectionWindow.xaml)
|
||||
- [PropertySelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/PropertySelectionViewModel.cs)
|
||||
- [CustomPropertiesWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/CustomPropertiesWindow.xaml)
|
||||
- [CustomPropertiesViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/CustomPropertiesViewModel.cs)
|
||||
- [ClilocSelectionWindow.xaml](file://ClassicAssist/UI/Views/Autoloot/ClilocSelectionWindow.xaml)
|
||||
- [ClilocSelectionViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Autoloot/ClilocSelectionViewModel.cs)
|
||||
|
||||
### Constraint Evaluation Flow
|
||||
The evaluation flow normalizes inputs, converts values to the expected property type, applies the operator, and aggregates results per rule.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Evaluate"]) --> ReadProps["Read item properties"]
|
||||
ReadProps --> Normalize["Normalize strings if needed"]
|
||||
Normalize --> Convert["Convert values to target type"]
|
||||
Convert --> ApplyOp["Apply operator to compare"]
|
||||
ApplyOp --> Aggregate["Aggregate with logical operators"]
|
||||
Aggregate --> Result{"Rule matched?"}
|
||||
Result --> |Yes| PickCandidate["Add to candidates"]
|
||||
Result --> |No| NextRule["Next rule"]
|
||||
PickCandidate --> Resolve["Resolve conflicts by priority"]
|
||||
Resolve --> Action["Pickup highest priority item"]
|
||||
NextRule --> End(["End"])
|
||||
Action --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
|
||||
### Integration with Inventory Management and Pickup Automation
|
||||
- IncomingPacketHandlers routes relevant packets to the autoloot manager.
|
||||
- ContainerContentsPacket and DropItem represent item arrivals that trigger evaluation.
|
||||
- Item provides the property surface used by constraints.
|
||||
- The manager coordinates with the targeting system to perform pickups.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Packet as "IncomingPacketHandlers"
|
||||
participant Event as "ContainerContentsPacket / DropItem"
|
||||
participant Manager as "AutolootManager"
|
||||
participant Item as "Item"
|
||||
participant Target as "Targeting System"
|
||||
Packet->>Event : "Dispatch packet"
|
||||
Event->>Manager : "OnItemArrival(item)"
|
||||
Manager->>Item : "Extract properties"
|
||||
Manager->>Manager : "Evaluate rules"
|
||||
alt "Match found"
|
||||
Manager->>Target : "Pickup(item)"
|
||||
else "No match"
|
||||
Manager-->>Packet : "No action"
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
|
||||
### Examples of Complex Rules
|
||||
- Example 1: Pick up any gold with quantity greater than 100 and hue not equal to a specific exclusion hue.
|
||||
- Example 2: Pick up potions whose name contains “Healing” and weight less than or equal to a threshold.
|
||||
- Example 3: Pick up items whose cliloc matches a localized string and has a custom property flag set.
|
||||
- Example 4: Exclude items owned by other players and only pick up items dropped at current location.
|
||||
|
||||
These examples illustrate combining multiple constraints, using operators like greater-than, contains, and equality, and applying logical grouping to refine behavior.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
|
||||
### Bulk Operations and Rule Testing
|
||||
- Bulk operations include enabling/disabling multiple rules, adjusting priorities, duplicating rules, and importing/exporting configurations.
|
||||
- Rule testing allows evaluating a rule against a selected item or a batch of items without executing pickups. Results indicate which constraints matched and why.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [AutolootTabControl.axaml](file://ClassicAssist.Avalonia/Views/Agents/AutolootTabControl.axaml)
|
||||
|
||||
## Dependency Analysis
|
||||
- AutolootManager depends on AutolootEntry, AutolootConstraintEntry, AutolootOperator, PropertyEntry, PropertyType, and AutolootHelpers.
|
||||
- UI components depend on AutolootViewModel and related view models for property and cliloc selection.
|
||||
- Network integration depends on IncomingPacketHandlers and specific packet classes to feed item events into the manager.
|
||||
- Tests depend on the manager and rule models to assert correct evaluation and conflict resolution.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VM["AutolootViewModel"] --> M["AutolootManager"]
|
||||
M --> E["AutolootEntry"]
|
||||
E --> C["AutolootConstraintEntry"]
|
||||
C --> O["AutolootOperator"]
|
||||
C --> P["PropertyEntry"]
|
||||
P --> PT["PropertyType"]
|
||||
M --> H["AutolootHelpers"]
|
||||
PH["IncomingPacketHandlers"] --> M
|
||||
CCP["ContainerContentsPacket"] --> PH
|
||||
DI["DropItem"] --> PH
|
||||
IT["Item"] --> M
|
||||
T["AutolootTests"] --> M
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
- [AutolootOperator.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootOperator.cs)
|
||||
- [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs)
|
||||
- [PropertyType.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyType.cs)
|
||||
- [AutolootHelpers.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootHelpers.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Rule evaluation complexity scales with the number of active rules and constraints. Prefer fewer high-precision rules over many broad ones.
|
||||
- Normalize and cache frequently accessed properties where possible to avoid repeated conversions.
|
||||
- Use short-circuit evaluation in logical expressions to fail fast on non-matching constraints.
|
||||
- Limit heavy operations (like regex or deep string processing) to necessary cases; prefer exact matches when feasible.
|
||||
- Batch testing should avoid triggering actual pickups; use dry-run mode for large sets.
|
||||
- Monitor memory usage by avoiding retaining references to large item collections after evaluation.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
- No items picked up: Verify rules are enabled and have higher priority than conflicting rules. Check that constraints match actual item properties.
|
||||
- Wrong items picked up: Inspect operator choices and value types; ensure proper normalization and case sensitivity settings.
|
||||
- Performance issues: Reduce rule count, simplify constraints, and disable unused rules.
|
||||
- Conflicting rules: Adjust priorities so the most specific rule wins. Use exclusions to prevent unintended matches.
|
||||
- Testing discrepancies: Ensure test input items reflect real-world properties and formats. Validate cliloc selections and custom properties.
|
||||
|
||||
**Section sources**
|
||||
- [AutolootTests.cs](file://ClassicAssist.Tests/Agents/AutolootTests.cs)
|
||||
- [AutolootViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/AutolootViewModel.cs)
|
||||
|
||||
## Conclusion
|
||||
The Autoloot agent provides a flexible, rule-driven system for automatic item pickup. By combining property-based constraints, operators, and logical grouping, users can craft precise behaviors while managing performance and conflicts through prioritization and testing tools. The UI facilitates rule creation and validation, and integration with packet handlers ensures timely evaluation upon item arrival.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
- Best practices:
|
||||
- Keep rules specific and ordered by priority.
|
||||
- Use exclusions to handle edge cases.
|
||||
- Regularly review and prune unused rules.
|
||||
- Leverage testing features before deploying changes.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
@@ -0,0 +1,449 @@
|
||||
# Dress Manager Agent
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml)
|
||||
- [DressAgentTests.cs](file://ClassicAssist.Tests/Agents/DressAgentTests.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
|
||||
## Introduction
|
||||
|
||||
The Dress Manager agent is a sophisticated automation system within ClassicAssist that manages character equipment sets and automates outfit changes based on various game scenarios. This feature allows players to create multiple dress profiles containing specific equipment configurations for different activities such as combat, crafting, social events, or exploration. The system intelligently switches between these profiles automatically or manually, ensuring optimal gear setup for any situation.
|
||||
|
||||
The Dress Manager provides a comprehensive solution for managing complex equipment setups, handling item validation, conditional outfit switching, and seamless integration with game events and skill checks. It supports both manual profile selection and automatic detection-based outfit changes, making it an essential tool for efficient gameplay management.
|
||||
|
||||
## Project Structure
|
||||
|
||||
The Dress Manager implementation follows a clean architecture pattern with clear separation between data models, business logic, user interface, and testing components:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Data Layer"
|
||||
DM[DressManager.cs]
|
||||
DAE[DressAgentEntry.cs]
|
||||
DAI[DressAgentItem.cs]
|
||||
DT[DressAgentItemType.cs]
|
||||
end
|
||||
subgraph "UI Layer"
|
||||
VM[DressTabViewModel.cs]
|
||||
XAML[DressTabControl.xaml]
|
||||
CS[DressTabControl.xaml.cs]
|
||||
end
|
||||
subgraph "Testing"
|
||||
TEST[DressAgentTests.cs]
|
||||
end
|
||||
subgraph "Game Integration"
|
||||
GAME[Game Engine]
|
||||
ITEMS[Item System]
|
||||
EVENTS[Event System]
|
||||
end
|
||||
DM --> DAE
|
||||
DM --> DAI
|
||||
DM --> DT
|
||||
VM --> DM
|
||||
XAML --> VM
|
||||
CS --> VM
|
||||
DM --> GAME
|
||||
DM --> ITEMS
|
||||
DM --> EVENTS
|
||||
TEST --> DM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml)
|
||||
- [DressAgentTests.cs](file://ClassicAssist.Tests/Agents/DressAgentTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml)
|
||||
- [DressAgentTests.cs](file://ClassicAssist.Tests/Agents/DressAgentTests.cs)
|
||||
|
||||
## Core Components
|
||||
|
||||
The Dress Manager system consists of several key components that work together to provide comprehensive equipment management functionality:
|
||||
|
||||
### Data Models
|
||||
|
||||
The core data structures define how dress profiles and items are represented:
|
||||
|
||||
- **DressAgentEntry**: Represents a complete dress profile containing all equipment slots and their configurations
|
||||
- **DressAgentItem**: Defines individual item specifications including item type, properties, and slot assignments
|
||||
- **DressAgentItemType**: Enumerates all possible equipment types and categories supported by the system
|
||||
- **DressManager**: Central orchestrator managing profile creation, validation, and outfit application
|
||||
|
||||
### User Interface Components
|
||||
|
||||
The UI layer provides intuitive management interfaces:
|
||||
|
||||
- **DressTabViewModel**: Manages the view model state and business logic for the dress manager interface
|
||||
- **DressTabControl**: Main tab control hosting the dress manager functionality
|
||||
- **XAML Layout**: Declarative UI definitions for profile management, item selection, and preview features
|
||||
|
||||
### Testing Framework
|
||||
|
||||
Comprehensive test coverage ensures reliability:
|
||||
|
||||
- **DressAgentTests**: Unit tests covering profile creation, item validation, and outfit switching scenarios
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml)
|
||||
- [DressAgentTests.cs](file://ClassicAssist.Tests/Agents/DressAgentTests.cs)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The Dress Manager follows a layered architecture pattern with clear separation of concerns:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User Interface"
|
||||
participant ViewModel as "DressTabViewModel"
|
||||
participant Manager as "DressManager"
|
||||
participant GameEngine as "Game Engine"
|
||||
participant ItemSystem as "Item System"
|
||||
User->>ViewModel : Create New Profile
|
||||
ViewModel->>Manager : AddProfile(profileName)
|
||||
Manager->>Manager : ValidateProfile()
|
||||
Manager-->>ViewModel : ProfileCreated
|
||||
User->>ViewModel : Add Item to Slot
|
||||
ViewModel->>Manager : AddItemToSlot(slotType, itemSpec)
|
||||
Manager->>ItemSystem : ValidateItem(itemSpec)
|
||||
ItemSystem-->>Manager : ValidationResult
|
||||
Manager-->>ViewModel : ItemAdded
|
||||
User->>ViewModel : Apply Outfit
|
||||
ViewModel->>Manager : ApplyOutfit(profileId)
|
||||
Manager->>GameEngine : EquipItems(items)
|
||||
GameEngine-->>Manager : EquipmentStatus
|
||||
Manager-->>ViewModel : OutfitApplied
|
||||
Note over Manager,GameEngine : Automatic Detection
|
||||
GameEngine->>Manager : OnCombatStart()
|
||||
Manager->>Manager : FindBestOutfit(combat)
|
||||
Manager->>GameEngine : AutoEquip(outfit)
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
|
||||
The architecture emphasizes:
|
||||
- **Separation of Concerns**: Clear boundaries between UI, business logic, and game integration
|
||||
- **Validation at Multiple Levels**: Item validation occurs during both configuration and application
|
||||
- **Event-Driven Updates**: Real-time synchronization between game state and UI
|
||||
- **Error Handling**: Comprehensive error management for missing items and invalid configurations
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Dress Manager Core Logic
|
||||
|
||||
The DressManager serves as the central coordinator for all dress-related operations:
|
||||
|
||||
#### Key Responsibilities
|
||||
- Profile lifecycle management (creation, modification, deletion)
|
||||
- Item validation and compatibility checking
|
||||
- Outfit application and rollback mechanisms
|
||||
- Conditional outfit switching based on game context
|
||||
- Performance optimization for large inventories
|
||||
|
||||
#### Data Flow Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Profile Creation]) --> ValidateInput["Validate Profile Input"]
|
||||
ValidateInput --> InputValid{"Input Valid?"}
|
||||
InputValid --> |No| ShowError["Display Validation Error"]
|
||||
InputValid --> |Yes| CreateProfile["Create Empty Profile"]
|
||||
CreateProfile --> AddItems["Add Items to Slots"]
|
||||
AddItems --> ValidateItems["Validate All Items"]
|
||||
ValidateItems --> ItemsValid{"All Items Valid?"}
|
||||
ItemsValid --> |No| FixItems["Guide User to Fix Issues"]
|
||||
ItemsValid --> |Yes| SaveProfile["Save Profile Configuration"]
|
||||
SaveProfile --> ReadyForUse["Profile Ready for Use"]
|
||||
ReadyForUse --> ManualSwitch["Manual Profile Switch"]
|
||||
ReadyForUse --> AutoSwitch["Automatic Context Switch"]
|
||||
ManualSwitch --> ApplyOutfit["Apply Selected Outfit"]
|
||||
AutoSwitch --> DetectContext["Detect Game Context"]
|
||||
DetectContext --> SelectBest["Select Best Matching Outfit"]
|
||||
SelectBest --> ApplyOutfit
|
||||
ApplyOutfit --> ValidateEquippable["Validate Equippable Items"]
|
||||
ValidateEquippable --> EquipSuccess{"Equipment Success?"}
|
||||
EquipSuccess --> |No| HandleErrors["Handle Missing/Invalid Items"]
|
||||
EquipSuccess --> |Yes| UpdateUI["Update UI State"]
|
||||
HandleErrors --> LogErrors["Log Errors and Warnings"]
|
||||
LogErrors --> PartialSuccess["Report Partial Success"]
|
||||
UpdateUI --> Complete([Operation Complete])
|
||||
PartialSuccess --> Complete
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
#### Conditional Outfit Switching Logic
|
||||
|
||||
The system supports sophisticated conditional logic for automatic outfit changes:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> CombatDetected : "Enter Combat"
|
||||
Idle --> CraftingDetected : "Start Crafting"
|
||||
Idle --> SocialDetected : "Enter Social Area"
|
||||
Idle --> ExplorationDetected : "Begin Exploration"
|
||||
CombatDetected --> EvaluateCombatGear["Evaluate Combat Gear"]
|
||||
CraftingDetected --> EvaluateCraftingGear["Evaluate Crafting Gear"]
|
||||
SocialDetected --> EvaluateSocialGear["Evaluate Social Gear"]
|
||||
ExplorationDetected --> EvaluateExplorationGear["Evaluate Exploration Gear"]
|
||||
EvaluateCombatGear --> HasBetterGear{"Has Better Combat Gear?"}
|
||||
EvaluateCraftingGear --> HasBetterCrafting{"Has Better Crafting Gear?"}
|
||||
EvaluateSocialGear --> HasBetterSocial{"Has Better Social Gear?"}
|
||||
EvaluateExplorationGear --> HasBetterExploration{"Has Better Exploration Gear?"}
|
||||
HasBetterGear --> |Yes| SwitchToCombat["Switch to Combat Outfit"]
|
||||
HasBetterCrafting --> |Yes| SwitchToCrafting["Switch to Crafting Outfit"]
|
||||
HasBetterSocial --> |Yes| SwitchToSocial["Switch to Social Outfit"]
|
||||
HasBetterExploration --> |Yes| SwitchToExploration["Switch to Exploration Outfit"]
|
||||
HasBetterGear --> |No| StayCurrent["Stay Current Outfit"]
|
||||
HasBetterCrafting --> |No| StayCurrent
|
||||
HasBetterSocial --> |No| StayCurrent
|
||||
HasBetterExploration --> |No| StayCurrent
|
||||
SwitchToCombat --> Idle
|
||||
SwitchToCrafting --> Idle
|
||||
SwitchToSocial --> Idle
|
||||
SwitchToExploration --> Idle
|
||||
StayCurrent --> Idle
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
### Item Slot Mapping System
|
||||
|
||||
The dress system uses a comprehensive slot mapping mechanism to ensure proper equipment placement:
|
||||
|
||||
#### Supported Equipment Slots
|
||||
- Head, Neck, Ear, Face, Hair, Beard
|
||||
- Chest, Arms, Hands, Legs, Feet
|
||||
- Waist, Ring Left, Ring Right
|
||||
- Weapon, Shield, Secondary Weapon
|
||||
- Clothing layers and special equipment slots
|
||||
|
||||
#### Slot Compatibility Rules
|
||||
- Armor type restrictions (light, medium, heavy)
|
||||
- Race and gender compatibility checks
|
||||
- Skill requirement validation
|
||||
- Stat minimum requirements
|
||||
- Faction and reputation restrictions
|
||||
|
||||
### Profile Management Features
|
||||
|
||||
#### Profile Creation Workflow
|
||||
1. **Template Selection**: Choose from predefined templates or start from scratch
|
||||
2. **Item Assignment**: Drag-and-drop items into appropriate slots
|
||||
3. **Conditional Rules**: Set up automatic switching conditions
|
||||
4. **Priority Settings**: Configure profile priority for conflict resolution
|
||||
5. **Validation**: Comprehensive validation before saving
|
||||
|
||||
#### Advanced Profile Features
|
||||
- **Nested Profiles**: Reference other profiles for component reuse
|
||||
- **Dynamic Items**: Items that change based on current game state
|
||||
- **Fallback Mechanisms**: Graceful degradation when preferred items unavailable
|
||||
- **Export/Import**: Share profiles between characters or accounts
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
|
||||
### User Interface Implementation
|
||||
|
||||
The UI provides an intuitive interface for managing dress profiles:
|
||||
|
||||
#### Main Interface Components
|
||||
- **Profile List**: Hierarchical display of all created profiles
|
||||
- **Item Grid**: Visual representation of equipment slots with drag-and-drop support
|
||||
- **Preview Panel**: Live preview of current and target outfits
|
||||
- **Condition Editor**: Visual editor for automatic switching rules
|
||||
- **Validation Status**: Real-time feedback on profile validity
|
||||
|
||||
#### Interactive Features
|
||||
- **Drag-and-Drop**: Intuitive item assignment to equipment slots
|
||||
- **Live Preview**: Immediate visual feedback when modifying profiles
|
||||
- **Bulk Operations**: Copy, paste, and batch modify multiple items
|
||||
- **Search and Filter**: Quick location of specific items across inventory
|
||||
- **Keyboard Shortcuts**: Efficient workflow for power users
|
||||
|
||||
**Section sources**
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/DressTabControl.xaml)
|
||||
|
||||
## Dependency Analysis
|
||||
|
||||
The Dress Manager has well-defined dependencies on core game systems:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "External Dependencies"
|
||||
GE[Game Engine]
|
||||
IS[Item System]
|
||||
ES[Event System]
|
||||
PM[Player Manager]
|
||||
IM[Inventory Manager]
|
||||
end
|
||||
subgraph "Internal Dependencies"
|
||||
DM[DressManager]
|
||||
DAE[DressAgentEntry]
|
||||
DAI[DressAgentItem]
|
||||
DT[DressAgentItemType]
|
||||
VM[DressTabViewModel]
|
||||
end
|
||||
DM --> GE
|
||||
DM --> IS
|
||||
DM --> ES
|
||||
DM --> PM
|
||||
DM --> IM
|
||||
VM --> DM
|
||||
DAE --> DAI
|
||||
DAE --> DT
|
||||
DAI --> DT
|
||||
GE --> IS
|
||||
ES --> GE
|
||||
PM --> IS
|
||||
IM --> IS
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [DressAgentItem.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItem.cs)
|
||||
- [DressAgentItemType.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentItemType.cs)
|
||||
- [DressTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/DressTabViewModel.cs)
|
||||
|
||||
### Integration Points
|
||||
|
||||
#### Game Event Integration
|
||||
- **Combat State Changes**: Automatic outfit switching on combat entry/exit
|
||||
- **Skill Activation**: Equipment adjustments for specific skills
|
||||
- **Location-Based Triggers**: Outfit changes in specific areas or dungeons
|
||||
- **Time-Based Conditions**: Different outfits for day/night cycles
|
||||
|
||||
#### Player State Monitoring
|
||||
- **Stat Changes**: Dynamic equipment adjustment based on stat improvements
|
||||
- **Level Progression**: Automatic updates when new equipment becomes available
|
||||
- **Quest Progress**: Context-aware outfit recommendations based on active quests
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
The Dress Manager implements several optimizations to handle large inventories efficiently:
|
||||
|
||||
### Memory Management
|
||||
- **Lazy Loading**: Items loaded on-demand rather than pre-loading entire inventories
|
||||
- **Caching Strategy**: Frequently accessed item data cached in memory
|
||||
- **Garbage Collection Optimization**: Minimize object creation during outfit switching
|
||||
|
||||
### Processing Optimization
|
||||
- **Batch Operations**: Group multiple equipment changes into single transactions
|
||||
- **Asynchronous Processing**: Non-blocking operations for time-consuming tasks
|
||||
- **Progressive Enhancement**: Basic outfit applied immediately, enhancements loaded in background
|
||||
|
||||
### Inventory Scaling
|
||||
- **Indexed Searches**: O(log n) item lookup using optimized data structures
|
||||
- **Filter Pipelines**: Efficient filtering of items by category, rarity, and requirements
|
||||
- **Memory Pooling**: Reuse of temporary objects during outfit validation
|
||||
|
||||
### Error Handling and Recovery
|
||||
- **Graceful Degradation**: System continues functioning even if some items unavailable
|
||||
- **Rollback Mechanisms**: Automatic revert to previous state on errors
|
||||
- **Diagnostic Logging**: Comprehensive logging for troubleshooting performance issues
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
#### Missing Items
|
||||
**Problem**: Items referenced in profiles not found in inventory
|
||||
**Solution**:
|
||||
- Verify item availability and ownership
|
||||
- Check for account-wide vs. character-specific items
|
||||
- Use fallback items in profile configuration
|
||||
|
||||
#### Equipment Conflicts
|
||||
**Problem**: Multiple items trying to occupy same slot
|
||||
**Solution**:
|
||||
- Review slot assignment in profile configuration
|
||||
- Ensure proper item type matching
|
||||
- Use priority settings to resolve conflicts
|
||||
|
||||
#### Performance Issues
|
||||
**Problem**: Slow outfit switching with large inventories
|
||||
**Solution**:
|
||||
- Enable lazy loading for infrequently used profiles
|
||||
- Optimize search filters in profile configuration
|
||||
- Consider splitting large profiles into smaller, focused sets
|
||||
|
||||
#### Automatic Switching Not Working
|
||||
**Problem**: Outfits not changing automatically as expected
|
||||
**Solution**:
|
||||
- Verify condition rules are properly configured
|
||||
- Check event subscription status
|
||||
- Review priority settings between conflicting profiles
|
||||
|
||||
### Debug Information
|
||||
|
||||
The system provides comprehensive debug output including:
|
||||
- Profile validation results with detailed error messages
|
||||
- Item compatibility analysis and failure reasons
|
||||
- Performance metrics for outfit switching operations
|
||||
- Event subscription status and trigger logs
|
||||
|
||||
**Section sources**
|
||||
- [DressAgentTests.cs](file://ClassicAssist.Tests/Agents/DressAgentTests.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Dress Manager agent represents a comprehensive solution for automated equipment management in ClassicAssist. Its modular architecture, robust validation system, and intuitive user interface make it an essential tool for players seeking to optimize their gameplay experience through intelligent outfit management.
|
||||
|
||||
Key strengths include:
|
||||
- **Flexibility**: Support for diverse equipment configurations and use cases
|
||||
- **Reliability**: Comprehensive error handling and validation mechanisms
|
||||
- **Performance**: Optimized for large inventories and frequent outfit changes
|
||||
- **Usability**: Intuitive interface with powerful advanced features
|
||||
|
||||
The system's extensible design allows for future enhancements while maintaining backward compatibility, ensuring long-term value for users. Whether managing simple daily wear or complex combat loadouts, the Dress Manager provides the foundation for sophisticated character customization and automation.
|
||||
@@ -0,0 +1,338 @@
|
||||
# Scavenger Agent
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
The Scavenger agent automates resource gathering and inventory management by continuously scanning the game world for items that match user-defined rules, moving to those items, targeting them, and collecting them into containers or the player’s backpack. It supports prioritization, conflict resolution when multiple scavengers target the same item, and integrates with movement and pathfinding systems to optimize travel. The UI allows users to create and manage scavenging profiles, configure collection priorities, and monitor activity.
|
||||
|
||||
## Project Structure
|
||||
The Scavenger feature spans data models, managers, UI view models, and tests:
|
||||
- Data layer defines entries and manager logic for scavenging rules and lifecycle.
|
||||
- UI layer provides a tabbed interface for managing entries and monitoring status.
|
||||
- Integration points connect to item discovery, targeting, movement, and container updates.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
SE["ScavengerEntry.cs"]
|
||||
SM["ScavengerManager.cs"]
|
||||
end
|
||||
subgraph "UI (Avalonia)"
|
||||
VM["ScavengerTabViewModel.cs"]
|
||||
XAML["ScavengerTabControl.xaml(.cs)"]
|
||||
end
|
||||
subgraph "Game Objects"
|
||||
ITEM["Item.cs"]
|
||||
EC["EntityCollection.cs"]
|
||||
end
|
||||
subgraph "Integration"
|
||||
TM["TargetManager.cs"]
|
||||
MC["MovementCommands.cs"]
|
||||
CCP["ContainerContentsPacket.cs"]
|
||||
end
|
||||
VM --> SM
|
||||
XAML --> VM
|
||||
SM --> SE
|
||||
SM --> EC
|
||||
SM --> ITEM
|
||||
SM --> TM
|
||||
SM --> MC
|
||||
SM --> CCP
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
## Core Components
|
||||
- ScavengerEntry: Represents a single scavenging rule including target identification criteria, priority, and behavior flags.
|
||||
- ScavengerManager: Orchestrates scanning, selection, routing, targeting, and collection; manages conflicts and state across entries.
|
||||
- ScavengerTabViewModel: Binds UI to manager operations, exposes collections and commands for adding/removing/editing entries and toggling activity.
|
||||
- ScavengerTabControl: Avalonia UI control hosting the tab content and binding to the view model.
|
||||
|
||||
Key responsibilities:
|
||||
- Rule evaluation against visible items.
|
||||
- Priority-based selection among candidates.
|
||||
- Movement and pathfinding integration to reach targets.
|
||||
- Targeting and interaction to collect items.
|
||||
- Inventory awareness to avoid overfilling and to route items to appropriate containers.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The Scavenger system follows a layered architecture:
|
||||
- UI Layer: Tab control and view model expose configuration and monitoring.
|
||||
- Manager Layer: Centralized orchestration of scanning, selection, movement, targeting, and collection.
|
||||
- Game Object Layer: Item and entity collections provide real-time world state.
|
||||
- Integration Layer: Targeting and movement subsystems execute actions on the client.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "ScavengerTabControl"
|
||||
participant VM as "ScavengerTabViewModel"
|
||||
participant Mgr as "ScavengerManager"
|
||||
participant World as "EntityCollection/Item"
|
||||
participant Move as "MovementCommands"
|
||||
participant Tgt as "TargetManager"
|
||||
participant Inv as "ContainerContentsPacket"
|
||||
UI->>VM : Load profile / toggle active
|
||||
VM->>Mgr : Start/Stop, Add/Remove Entry
|
||||
loop Scan Cycle
|
||||
Mgr->>World : Query visible items
|
||||
Mgr->>Mgr : Evaluate rules and priorities
|
||||
Mgr->>Move : Request move to target
|
||||
Move-->>Mgr : Movement status
|
||||
Mgr->>Tgt : Target item
|
||||
Tgt-->>Mgr : Target result
|
||||
Mgr->>Mgr : Attempt pickup/collection
|
||||
Inv-->>Mgr : Container update events
|
||||
Mgr->>Mgr : Update state and logs
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### ScavengerEntry
|
||||
Purpose:
|
||||
- Encapsulates a single scavenging rule with fields for target identification (e.g., item ID, properties), priority, and optional constraints (such as quantity thresholds or conditions).
|
||||
- Provides helpers to evaluate whether an item matches the entry’s criteria.
|
||||
|
||||
Design considerations:
|
||||
- Immutable or value-like semantics are preferred for rule stability during comparisons.
|
||||
- Matching logic should be efficient to support large item sets.
|
||||
|
||||
Usage examples:
|
||||
- Material gathering: Define entries for ore types with specific hues or names.
|
||||
- Crafting resources: Match items by property patterns or categories.
|
||||
- Valuable items: High-priority entries for rare loot.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
### ScavengerManager
|
||||
Responsibilities:
|
||||
- Maintains a list of ScavengerEntry instances.
|
||||
- Periodically scans EntityCollection for matching items.
|
||||
- Resolves conflicts when multiple entries target the same item using priority and last-seen timestamps.
|
||||
- Coordinates movement via MovementCommands and targeting via TargetManager.
|
||||
- Monitors inventory changes through container packet handlers to adapt collection strategies.
|
||||
|
||||
Algorithm highlights:
|
||||
- Candidate generation: Filter visible items by each entry’s matching function.
|
||||
- Conflict resolution: For overlapping candidates, select the highest priority entry; break ties with recency or distance heuristics.
|
||||
- Routing: Prefer nearby targets to minimize travel time; consider obstacles implicitly via movement commands.
|
||||
- Collection: After reaching proximity, target and attempt pickup; handle failures gracefully and retry if needed.
|
||||
|
||||
State and observability:
|
||||
- Exposes current activity status, last action, and counts of matched/targeted items.
|
||||
- Emits events or notifications consumed by the UI for live feedback.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
### ScavengerTabViewModel
|
||||
Role:
|
||||
- Bridges UI interactions to ScavengerManager.
|
||||
- Manages observable collections of entries and exposes commands for add/remove/edit/toggle.
|
||||
- Displays status indicators and recent activity logs.
|
||||
|
||||
User workflows:
|
||||
- Create new entries by selecting item identifiers and setting priority.
|
||||
- Reorder entries to adjust global precedence.
|
||||
- Enable/disable individual entries or the entire scavenger session.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
|
||||
### ScavengerTabControl (Avalonia)
|
||||
Role:
|
||||
- Hosts the Scavenger tab UI, binds to ScavengerTabViewModel, and renders lists, forms, and status panels.
|
||||
- Ensures thread-safe updates from background manager operations.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
|
||||
|
||||
### Example Profiles
|
||||
- Materials: Entries for common ores with moderate priority; lower priority for rarer variants.
|
||||
- Crafting Resources: Entries for herbs, leather, and reagents with medium priority; include property filters for quality if available.
|
||||
- Valuables: High-priority entries for gems or unique items; ensure they do not block essential resource collection by balancing priorities.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies:
|
||||
- ScavengerManager depends on:
|
||||
- ScavengerEntry for rule definitions.
|
||||
- EntityCollection and Item for world state.
|
||||
- MovementCommands for navigation.
|
||||
- TargetManager for targeting actions.
|
||||
- ContainerContentsPacket for inventory updates.
|
||||
- UI components depend on ScavengerTabViewModel, which delegates to ScavengerManager.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerEntry {
|
||||
+Match(item) bool
|
||||
+Priority int
|
||||
}
|
||||
class ScavengerManager {
|
||||
+Start()
|
||||
+Stop()
|
||||
+AddEntry(entry)
|
||||
+RemoveEntry(id)
|
||||
-SelectCandidate()
|
||||
-ResolveConflicts(candidates)
|
||||
-RouteTo(target)
|
||||
-Collect(target)
|
||||
}
|
||||
class ScavengerTabViewModel {
|
||||
+Entries ObservableCollection
|
||||
+IsActive bool
|
||||
+Start()
|
||||
+Stop()
|
||||
}
|
||||
class EntityCollection
|
||||
class Item
|
||||
class MovementCommands
|
||||
class TargetManager
|
||||
class ContainerContentsPacket
|
||||
ScavengerManager --> ScavengerEntry : "uses"
|
||||
ScavengerManager --> EntityCollection : "queries"
|
||||
ScavengerManager --> Item : "evaluates"
|
||||
ScavengerManager --> MovementCommands : "moves"
|
||||
ScavengerManager --> TargetManager : "targets"
|
||||
ScavengerManager --> ContainerContentsPacket : "listens"
|
||||
ScavengerTabViewModel --> ScavengerManager : "delegates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Efficient filtering: Keep ScavengerEntry matching logic lightweight; precompute stable attributes where possible.
|
||||
- Batched scanning: Avoid excessive polling; use event-driven updates from entity and container packets.
|
||||
- Intelligent routing: Prefer nearest targets and batch pickups along a path to reduce movement overhead.
|
||||
- Conflict resolution: Use priority and recency to minimize contention; avoid redundant targeting attempts.
|
||||
- Memory usage: Limit retained candidate lists; clear stale entries promptly.
|
||||
- Threading: Ensure UI updates are marshaled correctly; keep heavy work off the UI thread.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Items not collected: Verify visibility range and line-of-sight; check movement success logs; confirm targeting succeeded.
|
||||
- Conflicting entries: Adjust priorities so high-value items do not starve essential resources; review tie-breaking behavior.
|
||||
- Inventory full: Configure fallback behaviors such as dropping low-priority items or switching containers; monitor container updates.
|
||||
- Stuck movement: Inspect movement command responses; ensure pathfinding is functional and no obstacles block routes.
|
||||
- UI lag: Reduce number of active entries; throttle scan frequency; ensure background tasks are not blocking UI.
|
||||
|
||||
Validation references:
|
||||
- Unit tests cover core behaviors and edge cases for scavenger logic.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Conclusion
|
||||
The Scavenger agent provides a robust, configurable automation layer for resource gathering and inventory management. By combining precise rule definitions, intelligent routing, and strong integration with movement and targeting systems, it delivers reliable performance even in large areas. Properly configured profiles and priorities enable balanced collection strategies across materials, crafting resources, and valuables.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Creating Scavenger Profiles
|
||||
- Identify target items by ID, name, hue, or properties.
|
||||
- Assign priorities reflecting importance.
|
||||
- Group related items into cohesive profiles for different activities (mining, herbalism, looting).
|
||||
|
||||
[No sources needed since this section provides conceptual guidance]
|
||||
|
||||
### Monitoring Activity
|
||||
- Use the Scavenger tab to observe active entries, recent actions, and status indicators.
|
||||
- Review logs for failed movements or targeting attempts to refine rules and priorities.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
+389
@@ -0,0 +1,389 @@
|
||||
# Vendor Management Agents
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
|
||||
## Introduction
|
||||
This document explains the Vendor Management agents (Buy and Sell) that automate purchasing from and selling to NPC vendors. It covers how buy/sell lists are created, price tracking, stock monitoring, UI management, purchase limits, transaction history, integration with gold/inventory constraints, and error handling for common failure scenarios such as insufficient funds, inventory overflow, and vendor interaction failures.
|
||||
|
||||
## Project Structure
|
||||
The vendor system is implemented across shared data models, UI view models, and Avalonia UI controls:
|
||||
- Data models define entries for buy and sell lists and shop items.
|
||||
- View models manage list state, filtering, and actions.
|
||||
- Avalonia tabs host the user interfaces for configuring and operating the agents.
|
||||
- Network packets provide the low-level vendor buy operation.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
VBA["VendorBuyAgentEntry.cs"]
|
||||
VSA["VendorSellAgentEntry.cs"]
|
||||
SLE["ShopListEntry.cs"]
|
||||
SLSE["SellListEntry.cs"]
|
||||
XYC["XYComparer.cs"]
|
||||
end
|
||||
subgraph "UI ViewModels"
|
||||
VBVM["VendorBuyTabViewModel.cs"]
|
||||
VSVM["VendorSellTabViewModel.cs"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
VBTAB["VendorBuyTabControl.xaml.cs"]
|
||||
VSTAB["VendorSellTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "Network"
|
||||
VBP["VendorBuy.cs"]
|
||||
end
|
||||
VBA --> VBVM
|
||||
VSA --> VSVM
|
||||
SLE --> VBVM
|
||||
SLSE --> VSVM
|
||||
XYC --> VBVM
|
||||
XYC --> VSVM
|
||||
VBVM --> VBTAB
|
||||
VSVM --> VSTAB
|
||||
VBVM --> VBP
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Core Components
|
||||
- Buy agent entry: Represents a single item to purchase from a vendor, including quantity limits and optional price thresholds.
|
||||
- Sell agent entry: Represents an item to sell to a vendor, including minimum sell price or profit conditions.
|
||||
- Shop list entry: Represents an item available in a vendor’s shop, including price and stock information used for price tracking and stock monitoring.
|
||||
- Sell list entry: Represents an item in your inventory eligible for selling, including current count and sell price.
|
||||
- Comparer utilities: Provide sorting and comparison logic for vendor lists.
|
||||
- View models: Manage collections, filtering, selection, and operations for buy/sell tabs.
|
||||
- UI tabs: Host the interactive interface for managing vendor entries and running automation.
|
||||
- Network packet: Encapsulates the vendor buy request at the protocol level.
|
||||
|
||||
Key responsibilities:
|
||||
- Maintain persistent lists of items to buy/sell.
|
||||
- Track vendor prices and stock levels over time.
|
||||
- Enforce purchase limits and budget constraints.
|
||||
- Coordinate with inventory space checks before buying.
|
||||
- Present transaction history and status feedback.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The vendor agents operate through a layered architecture:
|
||||
- Data layer: Entry models store configuration and observed state (prices, stock).
|
||||
- ViewModel layer: Manages collections, filters, and orchestration of buy/sell workflows.
|
||||
- UI layer: Avalonia tabs render lists, allow editing, and trigger actions.
|
||||
- Network layer: Sends vendor buy requests via packets; other vendor interactions rely on existing network handlers.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UIBuy as "VendorBuyTabControl"
|
||||
participant VM as "VendorBuyTabViewModel"
|
||||
participant Model as "VendorBuyAgentEntry"
|
||||
participant Net as "VendorBuy Packet"
|
||||
User->>UIBuy : Open Buy Tab
|
||||
UIBuy->>VM : Initialize bindings
|
||||
User->>VM : Add/Edit entries<br/>Set purchase limits
|
||||
VM->>Model : Persist config
|
||||
User->>VM : Start automated buying
|
||||
VM->>VM : Check gold and inventory space
|
||||
VM->>Net : Send vendor buy request(s)
|
||||
Net-->>VM : Acknowledge result
|
||||
VM-->>UIBuy : Update status/history
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Buy Agent
|
||||
The buy agent automates purchasing items from NPCs based on configured lists and constraints.
|
||||
|
||||
- List creation: Users add items to the buy list with desired quantities and optional maximum price thresholds.
|
||||
- Price tracking: The system records vendor prices per item to compare against thresholds and detect price changes.
|
||||
- Stock monitoring: The system observes vendor stock availability and avoids attempting purchases when out of stock.
|
||||
- Purchase limits: Per-item limits prevent overbuying beyond configured caps.
|
||||
- Gold management: Before buying, the agent verifies sufficient gold and reserves funds accordingly.
|
||||
- Inventory constraints: The agent checks available backpack/container space before executing purchases.
|
||||
- Transaction history: Successful and failed transactions are logged with reasons for failures.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Buy Cycle"]) --> LoadEntries["Load Buy Entries"]
|
||||
LoadEntries --> ForEachEntry{"For each entry"}
|
||||
ForEachEntry --> |Yes| CheckPrice["Compare current price vs threshold"]
|
||||
CheckPrice --> PriceOK{"Within limit?"}
|
||||
PriceOK --> |No| SkipBuy["Skip due to price"]
|
||||
PriceOK --> |Yes| CheckStock["Check vendor stock"]
|
||||
CheckStock --> StockOK{"In stock?"}
|
||||
StockOK --> |No| SkipStock["Skip due to stock"]
|
||||
StockOK --> |Yes| CheckGold["Check gold balance"]
|
||||
CheckGold --> GoldOK{"Sufficient funds?"}
|
||||
GoldOK --> |No| FailGold["Fail: Insufficient funds"]
|
||||
GoldOK --> |Yes| CheckSpace["Check inventory space"]
|
||||
CheckSpace --> SpaceOK{"Space available?"}
|
||||
SpaceOK --> |No| FailSpace["Fail: Inventory overflow"]
|
||||
SpaceOK --> |Yes| ExecuteBuy["Send vendor buy request"]
|
||||
ExecuteBuy --> Record["Record transaction history"]
|
||||
Record --> NextEntry["Next entry"]
|
||||
SkipBuy --> NextEntry
|
||||
SkipStock --> NextEntry
|
||||
FailGold --> NextEntry
|
||||
FailSpace --> NextEntry
|
||||
NextEntry --> ForEachEntry
|
||||
ForEachEntry --> |No| End(["End Buy Cycle"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
### Sell Agent
|
||||
The sell agent automates selling unwanted items to NPCs based on configured lists and conditions.
|
||||
|
||||
- List creation: Users add items to the sell list with minimum acceptable sell prices or profit targets.
|
||||
- Price tracking: The system tracks vendor buyback prices to ensure profitability.
|
||||
- Stock monitoring: Not applicable for selling; however, it ensures items exist in inventory.
|
||||
- Sell limits: Per-item limits control how many units to sell.
|
||||
- Gold management: Selling increases gold; the agent can optionally enforce minimum gold thresholds before selling.
|
||||
- Inventory constraints: Selling frees space; the agent may prioritize high-value items first.
|
||||
- Transaction history: Logs sold items, prices, and outcomes.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
StartSell(["Start Sell Cycle"]) --> LoadSellEntries["Load Sell Entries"]
|
||||
LoadSellEntries --> ForEachSell{"For each sell entry"}
|
||||
ForEachSell --> |Yes| HasItem{"Item in inventory?"}
|
||||
HasItem --> |No| SkipNoItem["Skip: No item"]
|
||||
HasItem --> |Yes| CheckMinPrice["Compare sell price vs min price"]
|
||||
CheckMinPrice --> PriceOK{"Meets target?"}
|
||||
PriceOK --> |No| SkipPrice["Skip: Below target"]
|
||||
PriceOK --> |Yes| CheckLimit["Respect sell limit"]
|
||||
CheckLimit --> ExecuteSell["Send vendor sell request"]
|
||||
ExecuteSell --> RecordSell["Record transaction history"]
|
||||
RecordSell --> NextSell["Next sell entry"]
|
||||
SkipNoItem --> NextSell
|
||||
SkipPrice --> NextSell
|
||||
NextSell --> ForEachSell
|
||||
ForEachSell --> |No| EndSell(["End Sell Cycle"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
### UI for Managing Vendor Entries
|
||||
- Buy tab: Displays buy list entries, allows adding/removing/editing items, setting purchase limits, and toggling automation.
|
||||
- Sell tab: Displays sell list entries, allows configuring minimum sell prices and sell limits, and starting sell automation.
|
||||
- Filtering and sorting: Use comparer utilities to sort by name, price, or stock.
|
||||
- History panel: Shows recent transactions with success/failure indicators and reasons.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VendorBuyTabViewModel {
|
||||
+entries
|
||||
+filters
|
||||
+startBuying()
|
||||
+stopBuying()
|
||||
+addEntry(item, qty, maxPrice)
|
||||
+removeEntry(entry)
|
||||
+updateHistory(reason, item, qty)
|
||||
}
|
||||
class VendorSellTabViewModel {
|
||||
+sellEntries
|
||||
+filters
|
||||
+startSelling()
|
||||
+stopSelling()
|
||||
+addSellEntry(item, qty, minPrice)
|
||||
+removeSellEntry(entry)
|
||||
+updateHistory(reason, item, qty)
|
||||
}
|
||||
class VendorBuyAgentEntry {
|
||||
+item
|
||||
+quantity
|
||||
+maxPrice
|
||||
+enabled
|
||||
}
|
||||
class VendorSellAgentEntry {
|
||||
+item
|
||||
+quantity
|
||||
+minPrice
|
||||
+enabled
|
||||
}
|
||||
class ShopListEntry {
|
||||
+item
|
||||
+price
|
||||
+stock
|
||||
}
|
||||
class SellListEntry {
|
||||
+item
|
||||
+count
|
||||
+sellPrice
|
||||
}
|
||||
VendorBuyTabViewModel --> VendorBuyAgentEntry : "manages"
|
||||
VendorSellTabViewModel --> VendorSellAgentEntry : "manages"
|
||||
VendorBuyTabViewModel --> ShopListEntry : "reads prices/stock"
|
||||
VendorSellTabViewModel --> SellListEntry : "reads inventory/prices"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
### Concrete Usage Examples
|
||||
- Automated purchasing for crafting materials:
|
||||
- Add materials to the buy list with desired quantities and maximum prices.
|
||||
- Enable automation; the agent will periodically check prices and stock, then purchase within budget and space constraints.
|
||||
- Selling unwanted items:
|
||||
- Add items to the sell list with minimum acceptable sell prices.
|
||||
- Enable automation; the agent will sell items meeting criteria and log results.
|
||||
- Managing shop inventories:
|
||||
- Use price tracking and stock monitoring to identify profitable restocking opportunities.
|
||||
- Adjust purchase limits dynamically based on observed vendor stock levels.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Dependency Analysis
|
||||
The vendor components depend on shared data models and UI view models, with the buy flow integrating with the network layer for sending vendor buy requests.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VBA["VendorBuyAgentEntry.cs"] --> VBVM["VendorBuyTabViewModel.cs"]
|
||||
VSA["VendorSellAgentEntry.cs"] --> VSVM["VendorSellTabViewModel.cs"]
|
||||
SLE["ShopListEntry.cs"] --> VBVM
|
||||
SLSE["SellListEntry.cs"] --> VSVM
|
||||
XYC["XYComparer.cs"] --> VBVM
|
||||
XYC --> VSVM
|
||||
VBVM --> VBTAB["VendorBuyTabControl.xaml.cs"]
|
||||
VSVM --> VSTAB["VendorSellTabControl.xaml.cs"]
|
||||
VBVM --> VBP["VendorBuy.cs"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch operations: Group multiple buy/sell requests to reduce network overhead.
|
||||
- Debouncing: Avoid excessive polling by throttling price/stock checks.
|
||||
- Efficient comparisons: Use comparers for sorting large lists to minimize UI lag.
|
||||
- Memory usage: Keep only necessary history entries and prune old logs.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Insufficient funds:
|
||||
- Ensure gold balance meets total purchase cost.
|
||||
- Reduce purchase quantities or adjust maximum price thresholds.
|
||||
- Inventory overflow:
|
||||
- Verify available container space before buying.
|
||||
- Prioritize essential items or free up space by selling.
|
||||
- Vendor interaction failures:
|
||||
- Confirm vendor is targeted and accessible.
|
||||
- Retry after brief delay; check for server-side restrictions.
|
||||
- Price above threshold:
|
||||
- Adjust maximum price or wait for price drops.
|
||||
- Out of stock:
|
||||
- Monitor stock levels and schedule retries later.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
|
||||
## Conclusion
|
||||
The Vendor Management agents provide robust automation for buying and selling with NPCs. By leveraging configurable lists, price tracking, stock monitoring, and strict constraints around gold and inventory, users can efficiently manage crafting supplies and shop inventories while maintaining clear visibility into transaction history and errors.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
Reference in New Issue
Block a user