# Vendor Management **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) ## 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.