first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,417 @@
|
||||
# Buy Agents
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [BuyAgentTests.cs](file://ClassicAssist.Tests/Agents/BuyAgentTests.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
|
||||
This document explains the Vendor Buy Agent system that automatically purchases items from NPCs based on configured shop lists and criteria. It covers data structures, selection algorithms, price monitoring, stock tracking, automatic restocking triggers, UI configuration, common buying scenarios, and error handling for insufficient funds, vendor inventory limitations, and transaction failures.
|
||||
|
||||
## Project Structure
|
||||
The buy agent spans shared data models, network packet definitions, UI view models, and tests:
|
||||
- Data models define buy rules and shop entries.
|
||||
- Network packets model vendor interactions (opening vendor windows, requesting buys).
|
||||
- UI components provide a tabbed interface to create and manage buy rules.
|
||||
- Tests validate core behaviors.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
VBAE["VendorBuyAgentEntry.cs"]
|
||||
SLE["ShopListEntry.cs"]
|
||||
VSAE["VendorSellAgentEntry.cs"]
|
||||
XYC["XYComparer.cs"]
|
||||
end
|
||||
subgraph "UI"
|
||||
VM["VendorBuyTabViewModel.cs"]
|
||||
XAMLCS["VendorBuyTabControl.xaml.cs"]
|
||||
XAML["VendorBuyTabControl.xaml"]
|
||||
end
|
||||
subgraph "Network"
|
||||
VB["VendorBuy.cs"]
|
||||
CCP["ContainerContentsPacket.cs"]
|
||||
CCU["ContainerContentUpdate.cs"]
|
||||
UO["UseObject.cs"]
|
||||
CMC["ContextMenuClick.cs"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
BAT["BuyAgentTests.cs"]
|
||||
end
|
||||
VM --> VBAE
|
||||
VM --> SLE
|
||||
VM --> VSAE
|
||||
VM --> XYC
|
||||
VM --> VB
|
||||
VM --> CCP
|
||||
VM --> CCU
|
||||
VM --> UO
|
||||
VM --> CMC
|
||||
BAT --> VBAE
|
||||
BAT --> SLE
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [BuyAgentTests.cs](file://ClassicAssist.Tests/Agents/BuyAgentTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [BuyAgentTests.cs](file://ClassicAssist.Tests/Agents/BuyAgentTests.cs)
|
||||
|
||||
## Core Components
|
||||
- VendorBuyAgentEntry: Represents a single buy rule with item identifiers, quantity limits, price thresholds, vendor preferences, and state such as last purchase time or stock counters.
|
||||
- ShopListEntry: Defines an entry within a vendor’s shop list including item properties, price, and availability indicators used by the agent to match and select items.
|
||||
- VendorBuyTabViewModel: Binds the UI to buy rules, orchestrates scanning vendor inventories, applying selection criteria, and issuing purchase requests.
|
||||
- VendorBuyTabControl: Hosts the Avalonia UI for creating/editing buy rules and displaying status.
|
||||
- Network Packets: VendorBuy, ContainerContentsPacket, ContainerContentUpdate, UseObject, ContextMenuClick are used to open vendors, read shop contents, and request purchases.
|
||||
|
||||
Key responsibilities:
|
||||
- Maintain and persist buy rules.
|
||||
- Match vendor shop items against criteria.
|
||||
- Enforce quantity caps and price monitoring.
|
||||
- Trigger purchases when conditions are met.
|
||||
- Handle errors and update UI state.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The buy agent follows a pipeline:
|
||||
- User configures buy rules via the UI.
|
||||
- The agent periodically scans nearby vendors or reacts to vendor window events.
|
||||
- It reads vendor shop contents using container-related packets.
|
||||
- It applies selection algorithms (item matching, price checks, stock levels).
|
||||
- It issues purchase requests through vendor buy packets.
|
||||
- It updates internal state and UI feedback.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "VendorBuyTabControl"
|
||||
participant VM as "VendorBuyTabViewModel"
|
||||
participant Model as "VendorBuyAgentEntry / ShopListEntry"
|
||||
participant Net as "Network Packets"
|
||||
participant Game as "Game Server"
|
||||
UI->>VM : "Create/Edit Buy Rule"
|
||||
VM->>Model : "Persist rule"
|
||||
VM->>Net : "Open vendor / Request shop contents"
|
||||
Net-->>VM : "ContainerContentsPacket"
|
||||
VM->>VM : "Match items against criteria<br/>Check price and stock"
|
||||
alt "Conditions met"
|
||||
VM->>Net : "VendorBuy request"
|
||||
Net-->>Game : "Purchase attempt"
|
||||
Game-->>VM : "Result (success/failure)"
|
||||
VM->>Model : "Update counters and timestamps"
|
||||
VM->>UI : "Refresh status"
|
||||
else "No match or failure"
|
||||
VM->>Model : "Mark skipped or retry later"
|
||||
VM->>UI : "Show reason"
|
||||
end
|
||||
```
|
||||
|
||||
**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)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### VendorBuyAgentEntry
|
||||
Purpose:
|
||||
- Encapsulates a single buy rule with all necessary parameters for automated purchasing.
|
||||
- Tracks runtime state like last purchase timestamp, current stock count, and flags for enabling/disabling the rule.
|
||||
|
||||
Key aspects:
|
||||
- Item identification fields for matching vendor shop entries.
|
||||
- Quantity constraints (min/max per cycle or total).
|
||||
- Price threshold controls (max price, optional average price tracking).
|
||||
- Vendor preference filters (e.g., specific vendor types or locations).
|
||||
- State fields for cooldowns, retries, and logs.
|
||||
|
||||
Complexity:
|
||||
- O(1) access to rule fields; evaluation cost depends on matching logic in the ViewModel.
|
||||
|
||||
Error handling:
|
||||
- Validates numeric ranges and ensures required fields are set before activation.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
|
||||
### ShopListEntry
|
||||
Purpose:
|
||||
- Represents an item as it appears in a vendor’s shop list.
|
||||
- Provides attributes needed for matching and decision-making (price, quantity available, item IDs, etc.).
|
||||
|
||||
Key aspects:
|
||||
- Fields for item identity and properties.
|
||||
- Price and stock information parsed from vendor shop packets.
|
||||
- Comparison helpers to sort or filter shop items.
|
||||
|
||||
Complexity:
|
||||
- Matching is typically linear over the number of shop items.
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
### VendorBuyTabViewModel
|
||||
Responsibilities:
|
||||
- Loads and persists buy rules.
|
||||
- Orchestrates vendor discovery and shop scanning.
|
||||
- Applies selection algorithms and enforces constraints.
|
||||
- Issues purchase requests and handles responses.
|
||||
- Updates UI bindings for real-time feedback.
|
||||
|
||||
Selection algorithm overview:
|
||||
- Iterate enabled rules.
|
||||
- For each rule, scan vendor shop entries.
|
||||
- Match items by ID and other criteria.
|
||||
- Check price against thresholds.
|
||||
- Verify stock availability and quantity limits.
|
||||
- Select best candidate (e.g., lowest price among matches).
|
||||
- Execute purchase if all conditions pass.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Cycle"]) --> LoadRules["Load Enabled Rules"]
|
||||
LoadRules --> ForEachRule{"Next Rule?"}
|
||||
ForEachRule --> |No| End(["End Cycle"])
|
||||
ForEachRule --> |Yes| ScanVendor["Scan Vendor Shop Entries"]
|
||||
ScanVendor --> MatchItems["Match Items Against Criteria"]
|
||||
MatchItems --> HasMatch{"Any Matches?"}
|
||||
HasMatch --> |No| NextRule["Next Rule"]
|
||||
HasMatch --> CheckPrice["Check Price Thresholds"]
|
||||
CheckPrice --> PriceOK{"Within Budget?"}
|
||||
PriceOK --> |No| NextRule
|
||||
PriceOK --> CheckStock["Check Stock and Quantity Limits"]
|
||||
CheckStock --> StockOK{"Sufficient Stock?"}
|
||||
StockOK --> |No| NextRule
|
||||
StockOK --> Purchase["Issue Vendor Buy Request"]
|
||||
Purchase --> UpdateState["Update Rule State and UI"]
|
||||
UpdateState --> NextRule
|
||||
NextRule --> ForEachRule
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
|
||||
### UI Interface (VendorBuyTabControl)
|
||||
Features:
|
||||
- Create, edit, enable/disable buy rules.
|
||||
- Configure quantity limits and vendor preferences.
|
||||
- Display live status (last purchase time, remaining stock, errors).
|
||||
- Bindings to ViewModel for reactive updates.
|
||||
|
||||
User workflow:
|
||||
- Add a new rule and specify target items and constraints.
|
||||
- Save and enable the rule.
|
||||
- Monitor auto-purchases and adjust thresholds as needed.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml)
|
||||
|
||||
### Network Interactions
|
||||
- Opening vendor windows and reading shop contents rely on container-related packets.
|
||||
- Purchase requests use vendor buy packets.
|
||||
- Context menu actions may be used to initiate vendor interactions.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VendorBuy {
|
||||
+vendor_id
|
||||
+item_id
|
||||
+quantity
|
||||
}
|
||||
class ContainerContentsPacket {
|
||||
+container_id
|
||||
+entries[]
|
||||
}
|
||||
class ContainerContentUpdate {
|
||||
+container_id
|
||||
+changes[]
|
||||
}
|
||||
class UseObject {
|
||||
+target_id
|
||||
}
|
||||
class ContextMenuClick {
|
||||
+menu_id
|
||||
+button_id
|
||||
}
|
||||
VendorBuyTabViewModel --> VendorBuy : "issues"
|
||||
VendorBuyTabViewModel --> ContainerContentsPacket : "reads shop"
|
||||
VendorBuyTabViewModel --> ContainerContentUpdate : "reacts to changes"
|
||||
VendorBuyTabViewModel --> UseObject : "opens vendor"
|
||||
VendorBuyTabViewModel --> ContextMenuClick : "initiates interaction"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- VendorBuyTabViewModel depends on:
|
||||
- VendorBuyAgentEntry and ShopListEntry for rule data and shop item representation.
|
||||
- Network packets for vendor operations and shop content parsing.
|
||||
- UI components for user input and display.
|
||||
- VendorSellAgentEntry and XYComparer are related but not strictly required for buy logic; they support broader vendor functionality and comparisons.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VM["VendorBuyTabViewModel.cs"] --> VBAE["VendorBuyAgentEntry.cs"]
|
||||
VM --> SLE["ShopListEntry.cs"]
|
||||
VM --> VB["VendorBuy.cs"]
|
||||
VM --> CCP["ContainerContentsPacket.cs"]
|
||||
VM --> CCU["ContainerContentUpdate.cs"]
|
||||
VM --> UO["UseObject.cs"]
|
||||
VM --> CMC["ContextMenuClick.cs"]
|
||||
VM -. optional .-> VSAE["VendorSellAgentEntry.cs"]
|
||||
VM -. optional .-> XYC["XYComparer.cs"]
|
||||
```
|
||||
|
||||
**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)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.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)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Minimize repeated vendor scans by caching shop contents until updates arrive via container updates.
|
||||
- Prefer early exits in matching loops when criteria clearly fail.
|
||||
- Batch purchase requests where possible to reduce network overhead.
|
||||
- Debounce UI updates to avoid excessive redraws during bulk operations.
|
||||
- Use efficient comparators for sorting shop items by price or relevance.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Insufficient funds:
|
||||
- Ensure budget thresholds are set appropriately.
|
||||
- Review recent transactions and adjust max price or quantity limits.
|
||||
- Vendor inventory limitations:
|
||||
- Check stock counters and vendor refresh cycles.
|
||||
- Increase wait intervals between scans if vendors replenish slowly.
|
||||
- Transaction failures:
|
||||
- Validate vendor interaction sequence (open vendor, read shop, then buy).
|
||||
- Confirm correct item IDs and quantities in buy rules.
|
||||
- Inspect UI error messages and logs for server-side rejection reasons.
|
||||
|
||||
Operational tips:
|
||||
- Temporarily disable problematic rules to isolate issues.
|
||||
- Reduce rule complexity (fewer criteria) to verify baseline behavior.
|
||||
- Monitor last purchase timestamps to detect stalls.
|
||||
|
||||
**Section sources**
|
||||
- [BuyAgentTests.cs](file://ClassicAssist.Tests/Agents/BuyAgentTests.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
|
||||
## Conclusion
|
||||
The Vendor Buy Agent automates NPC purchases by combining configurable rules, robust selection algorithms, and precise network interactions. With clear UI controls and comprehensive error handling, it supports diverse scenarios such as bulk resource gathering, equipment upgrades, and consumable management. Properly tuning price thresholds, stock monitoring, and vendor preferences yields reliable, hands-free purchasing.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Common Buying Scenarios
|
||||
- Bulk resource gathering:
|
||||
- Set higher quantity limits and moderate price thresholds.
|
||||
- Enable periodic scans to keep inventory stocked.
|
||||
- Equipment upgrades:
|
||||
- Target specific item IDs with strict quality criteria.
|
||||
- Limit purchases to one per cycle to avoid overspending.
|
||||
- Consumable management:
|
||||
- Track minimum stock levels and trigger restocks automatically.
|
||||
- Use price averaging to smooth out market fluctuations.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
+426
@@ -0,0 +1,426 @@
|
||||
# Price Tracking & Analysis
|
||||
|
||||
<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)
|
||||
- [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)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.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)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
This document explains the Price Tracking and Analysis system within vendor management. It covers how NPC prices are monitored, historical pricing data is tracked, and cost analysis supports trading decisions. It also documents the XYComparer utility for price comparisons, price threshold configurations, market trend analysis, best vendor selection, price alerting, profit margin calculations, integration with buy and sell agents, optimization strategies (bulk purchase timing and market speculation), data storage considerations, performance characteristics for large datasets, and export capabilities for financial analysis.
|
||||
|
||||
## Project Structure
|
||||
The price tracking and analysis features are implemented across shared data models, UI view models, and network packet handling:
|
||||
|
||||
- Data models define entries for shop listings, sell lists, and agent-specific configuration for buying and selling.
|
||||
- A dedicated comparer utility enables consistent ordering and comparison of items by key attributes such as name and price.
|
||||
- UI tabs and view models expose controls and bindings to configure thresholds, display trends, and trigger actions.
|
||||
- Network handlers integrate with incoming vendor packets to capture live pricing updates.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
VBA["VendorBuyAgentEntry.cs"]
|
||||
VSA["VendorSellAgentEntry.cs"]
|
||||
SLE["ShopListEntry.cs"]
|
||||
SEL["SellListEntry.cs"]
|
||||
XYC["XYComparer.cs"]
|
||||
end
|
||||
subgraph "UI"
|
||||
VBTV["VendorBuyTabViewModel.cs"]
|
||||
VSTV["VendorSellTabViewModel.cs"]
|
||||
VBTC["VendorBuyTabControl.xaml.cs"]
|
||||
VSTC["VendorSellTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "Network"
|
||||
IPH["IncomingPacketHandlers.cs"]
|
||||
VBP["VendorBuy.cs"]
|
||||
end
|
||||
VBA --> VBTV
|
||||
VSA --> VSTV
|
||||
SLE --> VBTV
|
||||
SEL --> VSTV
|
||||
XYC --> VBTV
|
||||
XYC --> VSTV
|
||||
IPH --> VBP
|
||||
VBP --> VBTV
|
||||
VBP --> VSTV
|
||||
```
|
||||
|
||||
**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)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.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.Aavonia/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Core Components
|
||||
- Shop listing entry: Represents an item available from a vendor with properties used for price tracking and filtering.
|
||||
- Sell list entry: Represents an item configured for automated selling with thresholds and preferences.
|
||||
- Buy agent entry: Holds configuration for automated purchasing behavior, including thresholds and target vendors.
|
||||
- Sell agent entry: Holds configuration for automated selling behavior, including thresholds and target vendors.
|
||||
- XYComparer: Provides consistent comparison logic for sorting and ranking items by multiple criteria (e.g., name, price).
|
||||
- UI View Models: VendorBuyTabViewModel and VendorSellTabViewModel coordinate user interactions, thresholds, and display of price analytics.
|
||||
- Network Integration: IncomingPacketHandlers and VendorBuy packet types feed live vendor pricing into the system.
|
||||
|
||||
Key responsibilities:
|
||||
- Capture and store current and historical prices.
|
||||
- Compare and rank vendors based on price and other criteria.
|
||||
- Apply thresholds to trigger alerts or automated actions.
|
||||
- Compute profit margins and support decision-making.
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.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)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The system integrates real-time vendor pricing via network packets, persists and analyzes price history, and exposes controls for thresholds and automation. The flow below shows how incoming vendor data is processed and consumed by UI and automation components.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "Game Client"
|
||||
participant Net as "IncomingPacketHandlers.cs"
|
||||
participant Packet as "VendorBuy.cs"
|
||||
participant VM as "VendorBuyTabViewModel.cs / VendorSellTabViewModel.cs"
|
||||
participant Model as "ShopListEntry.cs / SellListEntry.cs"
|
||||
participant Agent as "VendorBuyAgentEntry.cs / VendorSellAgentEntry.cs"
|
||||
participant Comp as "XYComparer.cs"
|
||||
Game->>Net : "Vendor price update"
|
||||
Net->>Packet : "Parse VendorBuy packet"
|
||||
Packet-->>VM : "Item price data"
|
||||
VM->>Model : "Update current price and history"
|
||||
VM->>Agent : "Evaluate thresholds and rules"
|
||||
VM->>Comp : "Compare vendors and sort candidates"
|
||||
VM-->>Game : "Trigger buy/sell actions if conditions met"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Shop Listing Entry
|
||||
Purpose:
|
||||
- Captures item details and pricing information from vendor listings.
|
||||
- Supports filtering and historical tracking by maintaining fields for current and past prices.
|
||||
|
||||
Key aspects:
|
||||
- Fields for item identification and price values.
|
||||
- Methods or properties that enable updating and querying price history.
|
||||
- Compatibility with comparers for sorting and ranking.
|
||||
|
||||
Use cases:
|
||||
- Displaying current vendor prices.
|
||||
- Computing average, min, max over time windows.
|
||||
- Feeding trend analysis and alerting logic.
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
|
||||
### Sell List Entry
|
||||
Purpose:
|
||||
- Defines items intended for automated selling with configurable thresholds and preferences.
|
||||
|
||||
Key aspects:
|
||||
- Thresholds for minimum sell price or profit margin.
|
||||
- Flags or options controlling when to sell (e.g., immediate vs. delayed).
|
||||
- Integration with sell agent logic to execute sales.
|
||||
|
||||
Use cases:
|
||||
- Automated liquidation of inventory above configured thresholds.
|
||||
- Profit margin enforcement before selling.
|
||||
- Bulk sell operations guided by price trends.
|
||||
|
||||
**Section sources**
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
### Buy Agent Entry
|
||||
Purpose:
|
||||
- Configures automated purchasing behavior, including target vendors and price constraints.
|
||||
|
||||
Key aspects:
|
||||
- Thresholds for maximum buy price.
|
||||
- Best vendor selection criteria using comparers.
|
||||
- Rules for bulk purchases and timing.
|
||||
|
||||
Use cases:
|
||||
- Selecting the lowest-cost vendor meeting quality constraints.
|
||||
- Triggering purchases when prices drop below configured levels.
|
||||
- Coordinating with market trend analysis to optimize timing.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
|
||||
### Sell Agent Entry
|
||||
Purpose:
|
||||
- Configures automated selling behavior, including thresholds and execution policies.
|
||||
|
||||
Key aspects:
|
||||
- Minimum acceptable sell price or profit margin.
|
||||
- Timing strategies (immediate vs. wait for better price).
|
||||
- Integration with sell list entries and price history.
|
||||
|
||||
Use cases:
|
||||
- Selling at optimal times based on historical highs.
|
||||
- Enforcing profit targets before executing sales.
|
||||
- Managing risk by avoiding sells during downward trends.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### XYComparer Utility
|
||||
Purpose:
|
||||
- Provides consistent comparison logic for items, enabling reliable sorting and ranking across multiple criteria.
|
||||
|
||||
Key aspects:
|
||||
- Comparison by name, then by price or other attributes.
|
||||
- Stable ordering to ensure deterministic results.
|
||||
- Reusable across buy and sell workflows.
|
||||
|
||||
Use cases:
|
||||
- Ranking vendors by price for best vendor selection.
|
||||
- Sorting historical price snapshots for trend visualization.
|
||||
- Deterministic ordering for exports and reports.
|
||||
|
||||
**Section sources**
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
### UI Tabs and View Models
|
||||
Purpose:
|
||||
- Expose configuration and analytics for price tracking and automation.
|
||||
|
||||
Key aspects:
|
||||
- VendorBuyTabViewModel coordinates buy-related thresholds, vendor selection, and trend displays.
|
||||
- VendorSellTabViewModel coordinates sell-related thresholds, profit margins, and alerting.
|
||||
- Tab control code-behinds manage UI lifecycle and binding contexts.
|
||||
|
||||
Use cases:
|
||||
- Setting price thresholds and viewing alerts.
|
||||
- Analyzing trends and selecting optimal vendors.
|
||||
- Triggering manual or automated buy/sell actions.
|
||||
|
||||
**Section sources**
|
||||
- [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)
|
||||
|
||||
### Network Integration
|
||||
Purpose:
|
||||
- Captures live vendor pricing updates and feeds them into the system.
|
||||
|
||||
Key aspects:
|
||||
- IncomingPacketHandlers processes vendor-related packets.
|
||||
- VendorBuy packet type carries item price data.
|
||||
- Updates propagate to view models and data entries.
|
||||
|
||||
Use cases:
|
||||
- Real-time price monitoring.
|
||||
- Immediate threshold evaluation and alerting.
|
||||
- Updating historical records for trend analysis.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
### Price Alerting Flow
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Price Update Received"]) --> CheckThresholds["Check Buy/Sell Thresholds"]
|
||||
CheckThresholds --> BelowBuy{"Below Buy Threshold?"}
|
||||
BelowBuy --> |Yes| AlertBuy["Generate Buy Alert"]
|
||||
BelowBuy --> |No| AboveSell{"Above Sell Threshold?"}
|
||||
AboveSell --> |Yes| AlertSell["Generate Sell Alert"]
|
||||
AboveSell --> |No| NoAction["No Action"]
|
||||
AlertBuy --> EvaluateRules["Apply Automation Rules"]
|
||||
AlertSell --> EvaluateRules
|
||||
EvaluateRules --> ExecuteAction["Execute Buy/Sell or Notify User"]
|
||||
NoAction --> End(["End"])
|
||||
ExecuteAction --> End
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram maps dependencies among core components involved in price tracking and analysis.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ShopListEntry {
|
||||
+item_id
|
||||
+price
|
||||
+history
|
||||
}
|
||||
class SellListEntry {
|
||||
+item_id
|
||||
+sell_threshold
|
||||
+profit_margin
|
||||
}
|
||||
class VendorBuyAgentEntry {
|
||||
+buy_threshold
|
||||
+best_vendor_strategy
|
||||
}
|
||||
class VendorSellAgentEntry {
|
||||
+sell_threshold
|
||||
+timing_strategy
|
||||
}
|
||||
class XYComparer {
|
||||
+compare(itemA, itemB) int
|
||||
}
|
||||
class VendorBuyTabViewModel {
|
||||
+updatePrices()
|
||||
+evaluateBuy()
|
||||
+getBestVendor()
|
||||
}
|
||||
class VendorSellTabViewModel {
|
||||
+updatePrices()
|
||||
+evaluateSell()
|
||||
+computeMargin()
|
||||
}
|
||||
class IncomingPacketHandlers {
|
||||
+handleVendorBuy(packet)
|
||||
}
|
||||
class VendorBuy {
|
||||
+item_id
|
||||
+price
|
||||
}
|
||||
VendorBuyTabViewModel --> ShopListEntry : "reads/writes"
|
||||
VendorSellTabViewModel --> SellListEntry : "reads/writes"
|
||||
VendorBuyTabViewModel --> VendorBuyAgentEntry : "uses config"
|
||||
VendorSellTabViewModel --> VendorSellAgentEntry : "uses config"
|
||||
VendorBuyTabViewModel --> XYComparer : "sort/rank"
|
||||
VendorSellTabViewModel --> XYComparer : "sort/rank"
|
||||
IncomingPacketHandlers --> VendorBuy : "parses"
|
||||
IncomingPacketHandlers --> VendorBuyTabViewModel : "updates"
|
||||
IncomingPacketHandlers --> VendorSellTabViewModel : "updates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.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)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.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)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Efficient Comparisons: Use XYComparer consistently to avoid repeated custom sorting logic and ensure stable orderings.
|
||||
- History Management: Implement bounded buffers or rolling windows for price history to limit memory growth and maintain query performance.
|
||||
- Batch Updates: Coalesce frequent price updates into batched processing to reduce UI churn and computation overhead.
|
||||
- Indexing: Maintain indexes on frequently queried fields (e.g., item_id, timestamp) to speed up trend queries and exports.
|
||||
- Lazy Loading: Load detailed price histories on demand rather than upfront to improve startup and responsiveness.
|
||||
- Concurrency: Ensure thread-safe access to shared price data structures; use queues or locks where necessary to prevent race conditions.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Missing price updates: Verify IncomingPacketHandlers is wired to VendorBuy packets and that UI view models receive updates.
|
||||
- Incorrect vendor ranking: Confirm XYComparer is applied consistently and that comparison keys match expected semantics.
|
||||
- Thresholds not triggering: Check configuration in VendorBuyAgentEntry and VendorSellAgentEntry, and ensure thresholds are evaluated after each price update.
|
||||
- High memory usage: Inspect price history retention policies and implement rolling windows or periodic pruning.
|
||||
- Export failures: Validate data integrity and schema consistency before exporting; handle missing fields gracefully.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
## Conclusion
|
||||
The Price Tracking and Analysis system integrates live vendor pricing with robust data models, comparers, and UI-driven configuration. It supports best vendor selection, price alerting, profit margin calculations, and automation through buy and sell agents. By applying efficient comparison, careful history management, and clear threshold rules, users can make informed trading decisions, optimize bulk purchases, and engage in market speculation with confidence.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Price Optimization Strategies
|
||||
- Best Vendor Selection: Rank vendors using XYComparer and select the lowest-cost option meeting quality constraints.
|
||||
- Bulk Purchase Timing: Accumulate demand and execute purchases when prices fall below configured thresholds or when trend indicators suggest favorable conditions.
|
||||
- Market Speculation Tools: Monitor historical highs/lows and volatility; set dynamic thresholds that adapt to recent trends.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Data Storage for Price History
|
||||
- Store per-item price snapshots with timestamps.
|
||||
- Retain rolling windows to balance detail and performance.
|
||||
- Provide APIs for querying averages, minima, maxima, and trend metrics.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Export Capabilities for Financial Analysis
|
||||
- Export current prices and historical series to CSV or similar formats.
|
||||
- Include metadata such as item identifiers, vendor IDs, timestamps, and computed metrics (e.g., moving averages).
|
||||
- Ensure deterministic ordering using XYComparer for reproducible outputs.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
@@ -0,0 +1,375 @@
|
||||
# Sell Agents
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.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
|
||||
This document explains the Vendor Sell Agent system that automatically sells unwanted items to NPCs based on configurable sell lists and conditions. It covers the data structures, filtering logic, UI configuration, profit optimization features, price comparison across vendors, inventory cleanup strategies, and practical workflows such as junk disposal, loot processing, and maintenance routines. It also addresses considerations like vendor reputation effects, selling restrictions, and market value fluctuations.
|
||||
|
||||
## Project Structure
|
||||
The Vendor Sell Agent spans shared data models, UI view models, and tests:
|
||||
- Shared data models define agent entries, sell list entries, and related helpers.
|
||||
- Avalonia UI provides the tab control for managing sell rules.
|
||||
- Tests validate behavior and edge cases.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
VSAE["VendorSellAgentEntry.cs"]
|
||||
SLE["SellListEntry.cs"]
|
||||
VBAE["VendorBuyAgentEntry.cs"]
|
||||
SLEntry["ShopListEntry.cs"]
|
||||
XYC["XYComparer.cs"]
|
||||
end
|
||||
subgraph "UI (Avalonia)"
|
||||
VSTabVM["VendorSellTabViewModel.cs"]
|
||||
VSTabCtrl["VendorSellTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
SAT["SellAgentTests.cs"]
|
||||
end
|
||||
VSTabVM --> VSAE
|
||||
VSTabVM --> SLE
|
||||
VSTabCtrl --> VSTabVM
|
||||
SAT --> VSAE
|
||||
SAT --> SLE
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
|
||||
|
||||
## Core Components
|
||||
- VendorSellAgentEntry: Represents a configured sell agent instance with settings controlling which items are sold, thresholds, and behaviors.
|
||||
- SellListEntry: Defines individual sell rules including item criteria, minimum value, and exclusion flags.
|
||||
- VendorSellTabViewModel: Binds UI controls to agent configuration, exposes commands to add/remove/edit rules, and orchestrates selling operations.
|
||||
- VendorSellTabControl: Hosts the UI surface for managing sell rules and triggers actions from the ViewModel.
|
||||
- Supporting types: ShopListEntry and VendorBuyAgentEntry provide context for vendor interactions; XYComparer supports spatial comparisons when needed.
|
||||
|
||||
Key responsibilities:
|
||||
- Maintain collections of sell rules and agent options.
|
||||
- Evaluate inventory items against rules and thresholds.
|
||||
- Execute sell actions through vendor interfaces.
|
||||
- Persist and load configurations via the UI.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The sell flow is driven by the ViewModel, which reads agent configuration and applies filtering logic to inventory items. When an item matches a rule and meets thresholds, the agent initiates a sale through the vendor interface.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UI as "VendorSellTabControl"
|
||||
participant VM as "VendorSellTabViewModel"
|
||||
participant Agent as "VendorSellAgentEntry"
|
||||
participant Rule as "SellListEntry"
|
||||
participant Inv as "Inventory"
|
||||
participant Vendor as "Vendor Interface"
|
||||
User->>UI : Open Sell Rules Tab
|
||||
UI->>VM : Load Configuration
|
||||
VM->>Agent : Read Settings and Rules
|
||||
User->>UI : Trigger Sell Action
|
||||
UI->>VM : Execute Sell
|
||||
VM->>Inv : Enumerate Items
|
||||
loop For each Item
|
||||
VM->>Rule : Check Match and Thresholds
|
||||
alt Matches Rule and Meets Min Value
|
||||
VM->>Vendor : Sell Item
|
||||
Vendor-->>VM : Result
|
||||
else Does Not Match or Below Threshold
|
||||
VM->>VM : Skip Item
|
||||
end
|
||||
end
|
||||
VM-->>UI : Update Status and Summary
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [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)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### VendorSellAgentEntry
|
||||
Purpose:
|
||||
- Holds agent-level configuration such as enabled state, default thresholds, and global filters.
|
||||
- Provides accessors for rule evaluation and action execution.
|
||||
|
||||
Key aspects:
|
||||
- Global enable/disable toggle.
|
||||
- Default minimum value threshold if not specified per rule.
|
||||
- Flags to include/exclude categories or specific properties.
|
||||
- Integration points for vendor selection and transaction handling.
|
||||
|
||||
Complexity:
|
||||
- O(1) accessors for settings.
|
||||
- Rule iteration cost depends on number of rules.
|
||||
|
||||
Optimization opportunities:
|
||||
- Cache frequently accessed metadata (e.g., item categories).
|
||||
- Short-circuit evaluation when global disable is set.
|
||||
|
||||
Error handling:
|
||||
- Validate configuration on load.
|
||||
- Log invalid rules and skip them during evaluation.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### SellListEntry
|
||||
Purpose:
|
||||
- Encapsulates a single sell rule with match criteria and thresholds.
|
||||
|
||||
Attributes typically include:
|
||||
- Item identifier or pattern matching fields.
|
||||
- Minimum value threshold override.
|
||||
- Exclusion flags for valuable or special items.
|
||||
- Optional category or property constraints.
|
||||
|
||||
Evaluation logic:
|
||||
- Compare item attributes against rule fields.
|
||||
- Apply minimum value check using either rule-specific or agent-wide threshold.
|
||||
- Respect exclusion flags to protect high-value items.
|
||||
|
||||
Complexity:
|
||||
- Per-item evaluation is O(R) where R is number of active rules.
|
||||
- Sorting/comparison helpers may be used for ordering candidates.
|
||||
|
||||
Optimization opportunities:
|
||||
- Precompute normalized identifiers for faster matching.
|
||||
- Group rules by category to reduce comparisons.
|
||||
|
||||
Error handling:
|
||||
- Ignore malformed rules gracefully.
|
||||
- Provide clear diagnostics for unmatched expectations.
|
||||
|
||||
**Section sources**
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
### VendorSellTabViewModel
|
||||
Purpose:
|
||||
- Binds UI to agent configuration and rules.
|
||||
- Exposes commands to add, edit, remove, and reorder rules.
|
||||
- Orchestrates selling operations and updates UI state.
|
||||
|
||||
Responsibilities:
|
||||
- Initialize and persist configuration.
|
||||
- Manage observable collections of rules.
|
||||
- Handle user interactions and validation feedback.
|
||||
- Coordinate with VendorSellAgentEntry to execute sells.
|
||||
|
||||
Integration points:
|
||||
- VendorSellTabControl for rendering and input.
|
||||
- Underlying vendor interfaces for transactions.
|
||||
|
||||
Error handling:
|
||||
- Validate inputs before saving.
|
||||
- Report failures during selling with actionable messages.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
|
||||
### VendorSellTabControl
|
||||
Purpose:
|
||||
- Hosts the XAML layout and code-behind for the sell rules tab.
|
||||
- Wires up events and delegates to the ViewModel.
|
||||
|
||||
Responsibilities:
|
||||
- Display rule lists and forms.
|
||||
- Trigger ViewModel commands.
|
||||
- Reflect status changes and summaries.
|
||||
|
||||
Error handling:
|
||||
- Ensure UI remains responsive during long-running operations.
|
||||
- Surface errors to users without crashing.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
|
||||
### Supporting Types
|
||||
- ShopListEntry: Represents shop-related data used in vendor contexts.
|
||||
- VendorBuyAgentEntry: Related buy agent entry providing symmetry for purchase flows.
|
||||
- XYComparer: Utility for comparing coordinates or positions when relevant to vendor proximity.
|
||||
|
||||
Usage:
|
||||
- These types support vendor interaction and spatial decisions but are not core to sell rule evaluation.
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
### Class Diagram
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VendorSellAgentEntry {
|
||||
+bool Enabled
|
||||
+decimal DefaultMinValue
|
||||
+IEnumerable~SellListEntry~ Rules
|
||||
+Evaluate(item) bool
|
||||
+ExecuteSell(item) void
|
||||
}
|
||||
class SellListEntry {
|
||||
+string ItemIdOrPattern
|
||||
+decimal? MinValueOverride
|
||||
+bool ExcludeValuable
|
||||
+Match(item) bool
|
||||
}
|
||||
class VendorSellTabViewModel {
|
||||
+ObservableCollection~SellListEntry~ Rules
|
||||
+void AddRule()
|
||||
+void RemoveRule(rule)
|
||||
+void SaveConfiguration()
|
||||
+void ExecuteSell()
|
||||
}
|
||||
class VendorSellTabControl {
|
||||
+InitializeComponent()
|
||||
+OnSellClicked()
|
||||
}
|
||||
VendorSellTabViewModel --> VendorSellAgentEntry : "uses"
|
||||
VendorSellTabViewModel --> SellListEntry : "manages"
|
||||
VendorSellTabControl --> VendorSellTabViewModel : "binds to"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- VendorSellTabViewModel depends on VendorSellAgentEntry and SellListEntry for configuration and evaluation.
|
||||
- VendorSellTabControl depends on VendorSellTabViewModel for behavior.
|
||||
- Tests depend on both data models and ViewModel to assert correctness.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VSTabCtrl["VendorSellTabControl.xaml.cs"] --> VSTabVM["VendorSellTabViewModel.cs"]
|
||||
VSTabVM --> VSAE["VendorSellAgentEntry.cs"]
|
||||
VSTabVM --> SLE["SellListEntry.cs"]
|
||||
SAT["SellAgentTests.cs"] --> VSAE
|
||||
SAT --> SLE
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [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)
|
||||
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [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)
|
||||
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Rule evaluation complexity scales with the number of active rules; prefer concise patterns and categorization to minimize comparisons.
|
||||
- Use short-circuiting: disable the agent globally when not needed to avoid unnecessary enumeration.
|
||||
- Cache expensive lookups (e.g., item metadata) to reduce repeated work.
|
||||
- Batch sell operations where possible to reduce vendor interaction overhead.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- No items sold:
|
||||
- Verify agent is enabled and at least one rule exists.
|
||||
- Confirm minimum value thresholds are not too high.
|
||||
- Check exclusion flags that might protect items.
|
||||
- Incorrect items sold:
|
||||
- Review rule patterns and exclusions.
|
||||
- Ensure item identifiers or categories match expected values.
|
||||
- UI not updating:
|
||||
- Confirm bindings are correct in the ViewModel.
|
||||
- Check for exceptions in command handlers.
|
||||
- Vendor errors:
|
||||
- Inspect logs for transaction failures.
|
||||
- Validate vendor availability and reputation requirements.
|
||||
|
||||
Validation and logging:
|
||||
- The ViewModel should validate inputs and report errors clearly.
|
||||
- Tests can help reproduce and isolate issues.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
|
||||
|
||||
## Conclusion
|
||||
The Vendor Sell Agent system provides a flexible, configurable approach to automating item sales to NPCs. By combining structured sell rules, thresholds, and exclusion logic, it enables efficient inventory cleanup while protecting valuable items. The UI facilitates easy management of rules and thresholds, and tests ensure reliability. With careful tuning of rules and thresholds, players can optimize profits and maintain streamlined inventories.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Practical Examples
|
||||
- Junk item disposal:
|
||||
- Create rules targeting low-value junk categories with minimal thresholds.
|
||||
- Exclude any quest or unique items via exclusion flags.
|
||||
- Loot processing:
|
||||
- After combat, run the sell agent to quickly offload unneeded loot.
|
||||
- Use category-based rules to handle common drops efficiently.
|
||||
- Inventory maintenance:
|
||||
- Schedule periodic runs to keep backpacks organized.
|
||||
- Combine with other agents (e.g., organizer) for comprehensive management.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Profit Optimization and Price Comparison
|
||||
- Configure minimum value thresholds to avoid selling undervalued items.
|
||||
- Compare prices across multiple vendors by selecting the best option when available.
|
||||
- Monitor market fluctuations and adjust thresholds accordingly.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Vendor Reputation and Selling Restrictions
|
||||
- Some vendors may have reputation requirements or restricted selling capabilities.
|
||||
- Ensure the selected vendor is accessible and authorized for the intended sales.
|
||||
- Handle errors gracefully when restrictions prevent a sale.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
+448
@@ -0,0 +1,448 @@
|
||||
# Vendor Management
|
||||
|
||||
<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.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.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 system in ClassicAssist.Avalonia, focusing on automated trading agents that handle buying and selling operations with NPCs. It covers the data structures for buy/sell entries, shop list management, transaction automation, UI components for configuration, price monitoring, stock tracking, vendor interface integration, item validation, currency management, and common trading scenarios such as bulk purchasing, profit maximization, and inventory restocking. Error handling for insufficient funds, vendor limitations, and network connectivity issues is also addressed.
|
||||
|
||||
## Project Structure
|
||||
The Vendor Management feature spans shared data models, view models, Avalonia UI controls, and UO networking packets:
|
||||
- Data models define agent entries and shop lists for buy/sell operations.
|
||||
- View models provide state and commands to configure and run trades.
|
||||
- Avalonia tabs host the user interfaces for configuring buy/sell lists and monitoring transactions.
|
||||
- Networking packets encapsulate vendor buy requests sent to the game server.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Models"
|
||||
VBAE["VendorBuyAgentEntry"]
|
||||
VSAE["VendorSellAgentEntry"]
|
||||
SLE["ShopListEntry"]
|
||||
SLSE["SellListEntry"]
|
||||
XYC["XYComparer"]
|
||||
end
|
||||
subgraph "UI ViewModels"
|
||||
VBVM["VendorBuyTabViewModel"]
|
||||
VSVM["VendorSellTabViewModel"]
|
||||
end
|
||||
subgraph "Avalonia Views"
|
||||
VBTAB["VendorBuyTabControl"]
|
||||
VSTAB["VendorSellTabControl"]
|
||||
end
|
||||
subgraph "Networking"
|
||||
VBP["VendorBuy Packet"]
|
||||
end
|
||||
VBAE --> VBVM
|
||||
VSAE --> VSVM
|
||||
SLE --> VBVM
|
||||
SLSE --> VSVM
|
||||
VBTAB --> VBVM
|
||||
VSTAB --> VSVM
|
||||
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.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.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.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Core Components
|
||||
- VendorBuyAgentEntry: Represents a single buy rule or entry used by the buy agent to decide what to purchase from vendors.
|
||||
- VendorSellAgentEntry: Represents a single sell rule or entry used by the sell agent to decide what to sell to vendors.
|
||||
- ShopListEntry: Defines an item listing within a vendor’s shop catalog, including identifiers and pricing metadata.
|
||||
- SellListEntry: Defines an item listing for the player’s sell queue, including quantities and target prices.
|
||||
- XYComparer: Utility comparer used for sorting or ordering related to coordinates or indices (e.g., vendor positioning or list order).
|
||||
|
||||
These types form the backbone of the automated trading logic and are consumed by the UI view models to present and control buy/sell workflows.
|
||||
|
||||
**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)
|
||||
|
||||
## Architecture Overview
|
||||
The Vendor Management architecture follows a layered approach:
|
||||
- Data layer: Agent entries and shop/sell list entries model trade rules and catalogs.
|
||||
- Presentation layer: Avalonia tabs host UI for configuration and monitoring.
|
||||
- ViewModel layer: View models coordinate user actions, manage state, and orchestrate transactions.
|
||||
- Network layer: Vendor buy packet sends purchase requests to the server.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant BuyTab as "VendorBuyTabControl"
|
||||
participant VM as "VendorBuyTabViewModel"
|
||||
participant Model as "VendorBuyAgentEntry / ShopListEntry"
|
||||
participant Net as "VendorBuy Packet"
|
||||
User->>BuyTab : Configure buy list and start
|
||||
BuyTab->>VM : Bind and invoke Start()
|
||||
VM->>Model : Resolve items and prices
|
||||
VM->>Net : Send VendorBuy request(s)
|
||||
Net-->>VM : Server response (success/failure)
|
||||
VM-->>BuyTab : Update status, stock, and logs
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [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)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### VendorBuyAgentEntry
|
||||
Purpose:
|
||||
- Encapsulates a buy rule for the automated buy agent.
|
||||
- Typically includes item identification, desired quantity, maximum price, and optional filters.
|
||||
|
||||
Key responsibilities:
|
||||
- Matching against available shop items.
|
||||
- Enforcing price caps and quantity limits.
|
||||
- Integrating with stock checks before issuing purchases.
|
||||
|
||||
Common usage:
|
||||
- Populated via UI configuration.
|
||||
- Iterated by the buy workflow to generate purchase orders.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
|
||||
### VendorSellAgentEntry
|
||||
Purpose:
|
||||
- Encapsulates a sell rule for the automated sell agent.
|
||||
- Typically includes item identification, minimum sell price, and quantity constraints.
|
||||
|
||||
Key responsibilities:
|
||||
- Matching against vendor buyback prices.
|
||||
- Ensuring profitability thresholds.
|
||||
- Coordinating with inventory availability.
|
||||
|
||||
Common usage:
|
||||
- Configured through the sell tab UI.
|
||||
- Used by the sell workflow to propose sales.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### ShopListEntry
|
||||
Purpose:
|
||||
- Represents an item offered by a vendor in their shop catalog.
|
||||
- Contains fields for item ID, name, price, and possibly stock information.
|
||||
|
||||
Key responsibilities:
|
||||
- Providing a normalized representation of vendor offerings.
|
||||
- Supporting filtering and sorting by price or availability.
|
||||
|
||||
Integration points:
|
||||
- Consumed by the buy agent to match against VendorBuyAgentEntry rules.
|
||||
- Used by the UI to display shop contents and current prices.
|
||||
|
||||
**Section sources**
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
|
||||
### SellListEntry
|
||||
Purpose:
|
||||
- Represents an item queued for sale to a vendor.
|
||||
- Includes item identification, quantity, and target price.
|
||||
|
||||
Key responsibilities:
|
||||
- Tracking pending sells and completed transactions.
|
||||
- Enforcing minimum price constraints and quantity limits.
|
||||
|
||||
Integration points:
|
||||
- Managed by the sell workflow and UI.
|
||||
- Updated based on vendor buyback prices and inventory changes.
|
||||
|
||||
**Section sources**
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
|
||||
### XYComparer
|
||||
Purpose:
|
||||
- Utility comparer for ordering elements by X/Y-like properties or indices.
|
||||
- Often used to sort vendor positions or list entries deterministically.
|
||||
|
||||
Key responsibilities:
|
||||
- Providing consistent ordering for collections.
|
||||
- Supporting UI rendering stability and predictable processing order.
|
||||
|
||||
**Section sources**
|
||||
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
|
||||
|
||||
### VendorBuyTabViewModel
|
||||
Responsibilities:
|
||||
- Binds to VendorBuyTabControl and exposes buy list state.
|
||||
- Manages adding/removing VendorBuyAgentEntry items.
|
||||
- Orchestrates buy operations using ShopListEntry data.
|
||||
- Monitors stock levels and updates UI accordingly.
|
||||
- Handles errors such as insufficient funds or vendor limits.
|
||||
|
||||
Notable behaviors:
|
||||
- Validates entries before starting trades.
|
||||
- Queues and executes purchases while respecting price caps.
|
||||
- Updates progress indicators and logs.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
|
||||
### VendorSellTabViewModel
|
||||
Responsibilities:
|
||||
- Binds to VendorSellTabControl and exposes sell list state.
|
||||
- Manages adding/removing VendorSellAgentEntry items.
|
||||
- Orchestrates sell operations using SellListEntry data.
|
||||
- Tracks vendor buyback prices and enforces minimum profit thresholds.
|
||||
- Reports completion and error states.
|
||||
|
||||
Notable behaviors:
|
||||
- Validates sell entries prior to execution.
|
||||
- Coordinates with inventory and vendor constraints.
|
||||
- Provides feedback on successful and failed sales.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
|
||||
### VendorBuyTabControl (Avalonia)
|
||||
Responsibilities:
|
||||
- Hosts the buy configuration UI.
|
||||
- Binds to VendorBuyTabViewModel for two-way data binding.
|
||||
- Presents shop listings, stock counts, and transaction logs.
|
||||
|
||||
Interaction flow:
|
||||
- User edits buy rules and triggers automation.
|
||||
- ViewModel processes rules and interacts with network layer.
|
||||
- UI reflects real-time status and results.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
|
||||
### VendorSellTabControl (Avalonia)
|
||||
Responsibilities:
|
||||
- Hosts the sell configuration UI.
|
||||
- Binds to VendorSellTabViewModel for two-way data binding.
|
||||
- Displays sell queues, prices, and outcomes.
|
||||
|
||||
Interaction flow:
|
||||
- User configures sell rules and starts automation.
|
||||
- ViewModel validates and executes sales.
|
||||
- UI updates with progress and logs.
|
||||
|
||||
**Section sources**
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.cs)
|
||||
|
||||
### VendorBuy Packet
|
||||
Purpose:
|
||||
- Encapsulates the vendor buy request payload sent to the server.
|
||||
- Carries item IDs and quantities for purchase.
|
||||
|
||||
Usage:
|
||||
- Constructed by the buy workflow when a valid purchase decision is made.
|
||||
- Sent over the network; responses update stock and currency balances.
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
#### Class Diagram: Vendor Data Model
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VendorBuyAgentEntry {
|
||||
+ItemIdentifier
|
||||
+Quantity
|
||||
+MaxPrice
|
||||
+Filters
|
||||
}
|
||||
class VendorSellAgentEntry {
|
||||
+ItemIdentifier
|
||||
+MinPrice
|
||||
+Quantity
|
||||
}
|
||||
class ShopListEntry {
|
||||
+ItemId
|
||||
+Name
|
||||
+Price
|
||||
+Stock
|
||||
}
|
||||
class SellListEntry {
|
||||
+ItemId
|
||||
+Quantity
|
||||
+TargetPrice
|
||||
}
|
||||
class XYComparer {
|
||||
+Compare(x,y) int
|
||||
}
|
||||
VendorBuyAgentEntry --> ShopListEntry : "matches"
|
||||
VendorSellAgentEntry --> SellListEntry : "queues"
|
||||
ShopListEntry <.. XYComparer : "sorts"
|
||||
SellListEntry <.. XYComparer : "sorts"
|
||||
```
|
||||
|
||||
**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)
|
||||
|
||||
#### Sequence Diagram: Automated Buy Flow
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "VendorBuyTabControl"
|
||||
participant VM as "VendorBuyTabViewModel"
|
||||
participant Model as "ShopListEntry"
|
||||
participant Rule as "VendorBuyAgentEntry"
|
||||
participant Net as "VendorBuy Packet"
|
||||
UI->>VM : StartBuy()
|
||||
VM->>Model : Load shop items
|
||||
VM->>Rule : Evaluate price cap and filters
|
||||
alt Meets criteria
|
||||
VM->>Net : Send VendorBuy(itemId, qty)
|
||||
Net-->>VM : Success/Failure
|
||||
VM-->>UI : Update stock and logs
|
||||
else Does not meet criteria
|
||||
VM-->>UI : Skip item
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs)
|
||||
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
#### Flowchart: Profitability Check for Sells
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Sell Evaluation"]) --> LoadPrices["Load Vendor Buyback Prices"]
|
||||
LoadPrices --> Compare{"Meets Min Price?"}
|
||||
Compare --> |No| Skip["Skip Item"]
|
||||
Compare --> |Yes| CheckQty["Check Inventory Quantity"]
|
||||
CheckQty --> HasQty{"Has Enough Stock?"}
|
||||
HasQty --> |No| Insufficient["Log Insufficient Stock"]
|
||||
HasQty --> |Yes| QueueSell["Queue Sell Entry"]
|
||||
QueueSell --> End(["End"])
|
||||
Insufficient --> End
|
||||
Skip --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
|
||||
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- VendorBuyTabViewModel depends on VendorBuyAgentEntry and ShopListEntry to evaluate and execute buys.
|
||||
- VendorSellTabViewModel depends on VendorSellAgentEntry and SellListEntry to evaluate and execute sells.
|
||||
- Both view models rely on Avalonia tab controls for UI binding and interaction.
|
||||
- The buy workflow uses the VendorBuy packet to communicate with the server.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VBT["VendorBuyTabControl"] --> VBVM["VendorBuyTabViewModel"]
|
||||
VST["VendorSellTabControl"] --> VSVM["VendorSellTabViewModel"]
|
||||
VBVM --> VBAE["VendorBuyAgentEntry"]
|
||||
VBVM --> SLE["ShopListEntry"]
|
||||
VSVM --> VSAE["VendorSellAgentEntry"]
|
||||
VSVM --> SLSE["SellListEntry"]
|
||||
VBVM --> VBP["VendorBuy Packet"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.cs)
|
||||
- [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)
|
||||
- [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)
|
||||
- [VendorBuyTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.axaml.cs)
|
||||
- [VendorSellTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.axaml.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)
|
||||
- [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch operations: Group multiple buy/sell requests where possible to reduce network overhead.
|
||||
- Efficient matching: Use comparers and indexes to quickly filter shop items and inventory.
|
||||
- Throttling: Avoid flooding the server with rapid requests; introduce small delays between transactions.
|
||||
- UI responsiveness: Offload heavy computations to background tasks and marshal updates to the UI thread.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Insufficient funds:
|
||||
- Ensure the player has enough gold before initiating buys.
|
||||
- Validate budget constraints in the buy agent configuration.
|
||||
- Vendor limitations:
|
||||
- Respect per-item purchase limits enforced by the vendor.
|
||||
- Handle cases where stock drops below requested quantity.
|
||||
- Network connectivity issues:
|
||||
- Retry failed transactions with backoff.
|
||||
- Provide clear error messages and allow manual resumption.
|
||||
- Price volatility:
|
||||
- Re-evaluate prices before each transaction to avoid outdated assumptions.
|
||||
- Log discrepancies between expected and actual costs.
|
||||
|
||||
Operational tips:
|
||||
- Monitor logs for failures and partial successes.
|
||||
- Use stock tracking to prevent overselling or overbuying.
|
||||
- Confirm vendor interactions are active and reachable before starting automation.
|
||||
|
||||
**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 system integrates structured data models, robust view models, and Avalonia UI components to automate buying and selling with NPCs. By leveraging VendorBuyAgentEntry and VendorSellAgentEntry alongside ShopListEntry and SellListEntry, the system supports flexible trading strategies, price monitoring, and stock tracking. Proper error handling ensures resilience against insufficient funds, vendor limits, and network issues, enabling reliable bulk purchasing, profit maximization, and inventory restocking workflows.
|
||||
Reference in New Issue
Block a user