Beyhan Oğur
20 KiB
20 KiB
Buy Agents
**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)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- 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.
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
- ShopListEntry.cs
- VendorSellAgentEntry.cs
- XYComparer.cs
- VendorBuyTabViewModel.cs
- VendorBuyTabControl.xaml.cs
- VendorBuyTabControl.xaml
- VendorBuy.cs
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- ContextMenuClick.cs
- BuyAgentTests.cs
Section sources
- VendorBuyAgentEntry.cs
- ShopListEntry.cs
- VendorBuyTabViewModel.cs
- VendorBuyTabControl.xaml.cs
- VendorBuyTabControl.xaml
- VendorBuy.cs
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- ContextMenuClick.cs
- 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
- ShopListEntry.cs
- VendorBuyTabViewModel.cs
- VendorBuyTabControl.xaml.cs
- VendorBuyTabControl.xaml
- VendorBuy.cs
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- 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.
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
- VendorBuyTabViewModel.cs
- VendorBuyAgentEntry.cs
- ShopListEntry.cs
- ContainerContentsPacket.cs
- 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
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
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.
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
Section sources
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
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.
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
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- ContextMenuClick.cs
- VendorBuyTabViewModel.cs
Section sources
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.
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
- VendorBuyAgentEntry.cs
- ShopListEntry.cs
- VendorBuy.cs
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- ContextMenuClick.cs
- VendorSellAgentEntry.cs
- XYComparer.cs
Section sources
- VendorBuyTabViewModel.cs
- VendorBuyAgentEntry.cs
- ShopListEntry.cs
- VendorSellAgentEntry.cs
- XYComparer.cs
- VendorBuy.cs
- ContainerContentsPacket.cs
- ContainerContentUpdate.cs
- UseObject.cs
- 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
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]