first commit
This commit is contained in:
Beyhan Oğur
+479
@@ -0,0 +1,479 @@
|
||||
# Inventory Integration
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
|
||||
## Introduction
|
||||
|
||||
The Scavenger Agent in ClassicAssist.Avalonia is a sophisticated automated inventory management system designed to collect items from the game world and intelligently organize them within the player's inventory. This document provides comprehensive technical documentation for understanding how the scavenger system integrates with the player's backpack, containers, and equipment slots during item collection operations.
|
||||
|
||||
The scavenger system operates as part of ClassicAssist's agent framework, working alongside other automation agents like the Organizer and Dress agents to provide seamless inventory management. It implements intelligent decision-making algorithms for item placement, conflict resolution when inventory space is limited, and coordination with other agents for optimal resource utilization.
|
||||
|
||||
## Project Structure
|
||||
|
||||
The Scavenger Agent implementation follows ClassicAssist's modular architecture pattern, with clear separation between data models, business logic, and user interface components:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "UI Layer"
|
||||
STC["ScavengerTabControl.axaml.cs"]
|
||||
STV["ScavengerTabViewModel.cs"]
|
||||
end
|
||||
subgraph "Business Logic"
|
||||
SM["ScavengerManager.cs"]
|
||||
SE["ScavengerEntry.cs"]
|
||||
end
|
||||
subgraph "Game Integration"
|
||||
PM["PlayerMobile.cs"]
|
||||
IT["Item.cs"]
|
||||
CCP["ContainerContentsPacket.cs"]
|
||||
end
|
||||
subgraph "Related Agents"
|
||||
OM["OrganizerManager.cs"]
|
||||
DM["DressManager.cs"]
|
||||
end
|
||||
STC --> STV
|
||||
STV --> SM
|
||||
SM --> SE
|
||||
SM --> PM
|
||||
SM --> IT
|
||||
SM --> CCP
|
||||
SM --> OM
|
||||
SM --> DM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
## Core Components
|
||||
|
||||
### Scavenger Manager Architecture
|
||||
|
||||
The Scavenger Manager serves as the central orchestrator for all scavenging operations, coordinating between game state monitoring, inventory management, and inter-agent communication.
|
||||
|
||||
#### Key Responsibilities:
|
||||
- **Item Detection**: Monitoring game world for eligible items based on scavenger rules
|
||||
- **Inventory Assessment**: Evaluating current inventory capacity and container availability
|
||||
- **Placement Decision Engine**: Determining optimal storage locations for collected items
|
||||
- **Conflict Resolution**: Managing inventory space constraints and item movement requirements
|
||||
- **Agent Coordination**: Communicating with Organizer and Dress agents for integrated workflows
|
||||
|
||||
#### Data Flow Architecture:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "Game World"
|
||||
participant Scavenger as "ScavengerManager"
|
||||
participant Inventory as "PlayerInventory"
|
||||
participant Organizer as "OrganizerManager"
|
||||
participant Dress as "DressManager"
|
||||
Game->>Scavenger : Item detected
|
||||
Scavenger->>Scavenger : Validate against rules
|
||||
Scavenger->>Inventory : Check capacity
|
||||
alt Space Available
|
||||
Inventory->>Inventory : Place item in optimal location
|
||||
Scavenger->>Organizer : Notify for sorting
|
||||
Organizer-->>Scavenger : Sorting complete
|
||||
else No Space
|
||||
Scavenger->>Scavenger : Evaluate move options
|
||||
Scavenger->>Organizer : Request bulk organization
|
||||
Organizer->>Inventory : Move items to make room
|
||||
Inventory->>Scavenger : Space created
|
||||
Scavenger->>Inventory : Place target item
|
||||
end
|
||||
Scavenger->>Dress : Update equipment if needed
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
### Container Priority System
|
||||
|
||||
The scavenger system implements a sophisticated priority-based container selection algorithm that considers multiple factors when determining where to place collected items:
|
||||
|
||||
#### Container Type Priorities:
|
||||
1. **Backpack Slots**: Primary storage for frequently accessed items
|
||||
2. **Equipment Slots**: Specialized storage for wearable items
|
||||
3. **Personal Containers**: Player-owned containers with specific purposes
|
||||
4. **Shared Containers**: Guild or party containers for shared resources
|
||||
5. **Vendor Containers**: Temporary storage near vendor locations
|
||||
|
||||
#### Placement Decision Factors:
|
||||
- **Item Stackability**: Whether items can be combined with existing stacks
|
||||
- **Container Capacity**: Remaining space in target containers
|
||||
- **Access Frequency**: How often the item needs to be retrieved
|
||||
- **Item Value**: Strategic importance of item accessibility
|
||||
- **Storage Rules**: User-defined preferences and organizational schemes
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The Scavenger Agent operates within ClassicAssist's broader agent ecosystem, maintaining loose coupling while enabling coordinated behavior through well-defined interfaces.
|
||||
|
||||
### System Integration Points:
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerManager {
|
||||
+ScavengerEntry[] entries
|
||||
+bool isEnabled
|
||||
+DateTime lastCollectionTime
|
||||
+CollectItems() void
|
||||
+EvaluatePlacement(Item item) Container
|
||||
+ResolveConflicts() bool
|
||||
+UpdateInventoryState() void
|
||||
}
|
||||
class ScavengerEntry {
|
||||
+string name
|
||||
+int[] itemTypes
|
||||
+bool includeSubtypes
|
||||
+int maxQuantity
|
||||
+bool autoEquip
|
||||
+bool addToOrganizer
|
||||
+ValidateItem(Item item) bool
|
||||
+GetPriority() int
|
||||
}
|
||||
class PlayerInventory {
|
||||
+Item[] backpack
|
||||
+Dictionary~Slot, Item~ equipment
|
||||
+Container[] personalContainers
|
||||
+CheckCapacity() bool
|
||||
+FindOptimalLocation(Item item) Container
|
||||
+PlaceItem(Item item, Container target) bool
|
||||
+MoveItem(Item source, Container destination) bool
|
||||
}
|
||||
class OrganizerManager {
|
||||
+OrganizerEntry[] rules
|
||||
+bool autoSortEnabled
|
||||
+SortInventory() void
|
||||
+MakeRoomForItem(Item newItem) bool
|
||||
+BulkOrganize() void
|
||||
}
|
||||
class DressManager {
|
||||
+DressAgentEntry[] outfits
|
||||
+bool autoDressEnabled
|
||||
+UpdateEquipment(Item equippedItem) void
|
||||
+ApplyOutfit(string outfitName) void
|
||||
+CoordinateWithScavenger(bool enabled) void
|
||||
}
|
||||
ScavengerManager --> PlayerInventory : "manages"
|
||||
ScavengerManager --> OrganizerManager : "coordinates with"
|
||||
ScavengerManager --> DressManager : "coordinates with"
|
||||
ScavengerManager --> ScavengerEntry : "contains"
|
||||
PlayerInventory --> Item : "stores"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
|
||||
### Event-Driven Communication Pattern
|
||||
|
||||
The scavenger system utilizes an event-driven architecture to maintain real-time synchronization with game state changes and coordinate with other agents:
|
||||
|
||||
#### Key Events:
|
||||
- **ItemCollected**: Triggered when an item is successfully added to inventory
|
||||
- **ContainerFull**: Emitted when target container reaches capacity
|
||||
- **SpaceCreated**: Notified when organizer creates inventory space
|
||||
- **EquipmentChanged**: Broadcast when dress agent modifies equipment
|
||||
- **InventoryResync**: Periodic update to ensure state consistency
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Scavenger Entry Configuration System
|
||||
|
||||
Each scavenger entry represents a specific item collection rule with configurable parameters that determine how items matching those criteria should be handled.
|
||||
|
||||
#### Configuration Properties:
|
||||
- **Item Type Filters**: Specific item IDs or type ranges to collect
|
||||
- **Quality Thresholds**: Minimum quality or value requirements
|
||||
- **Stack Management**: Rules for handling stackable vs non-stackable items
|
||||
- **Destination Preferences**: Preferred storage locations and fallback options
|
||||
- **Auto-Equip Settings**: Automatic equipment application for wearable items
|
||||
- **Organizer Integration**: Whether to include items in automatic sorting
|
||||
|
||||
#### Advanced Filtering Capabilities:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([New Item Detected]) --> CheckType["Check Item Type Against Rules"]
|
||||
CheckType --> TypeMatch{"Type Matches?"}
|
||||
TypeMatch --> |No| SkipItem["Skip Item Collection"]
|
||||
TypeMatch --> |Yes| CheckQuality["Evaluate Item Quality/Value"]
|
||||
CheckQuality --> QualityPass{"Meets Quality Threshold?"}
|
||||
QualityPass --> |No| SkipItem
|
||||
QualityPass --> |Yes| CheckStackable["Determine Stackability"]
|
||||
CheckStackable --> IsStackable{"Is Stackable?"}
|
||||
IsStackable --> |Yes| FindExistingStack["Locate Existing Stack"]
|
||||
IsStackable --> |No| FindEmptySlot["Find Empty Container Slot"]
|
||||
FindExistingStack --> StackHasSpace{"Stack Has Space?"}
|
||||
StackHasSpace --> |Yes| AddToStack["Add to Existing Stack"]
|
||||
StackHasSpace --> |No| CreateNewStack["Create New Stack"]
|
||||
FindEmptySlot --> PlaceInContainer["Place in Target Container"]
|
||||
AddToStack --> CheckAutoEquip["Check Auto-Equip Rules"]
|
||||
CreateNewStack --> CheckAutoEquip
|
||||
PlaceInContainer --> CheckAutoEquip
|
||||
CheckAutoEquip --> AutoEquip{"Auto-Equip Enabled?"}
|
||||
AutoEquip --> |Yes| ApplyEquipment["Apply Equipment Changes"]
|
||||
AutoEquip --> |No| CheckOrganizer["Check Organizer Integration"]
|
||||
ApplyEquipment --> CheckOrganizer
|
||||
CheckOrganizer --> IncludeInSorting{"Include in Auto-Sorting?"}
|
||||
IncludeInSorting --> |Yes| QueueForSorting["Queue for Organizer Processing"]
|
||||
IncludeInSorting --> |No| Complete(["Collection Complete"])
|
||||
QueueForSorting --> Complete
|
||||
SkipItem --> End([End])
|
||||
Complete --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### Conflict Resolution Mechanisms
|
||||
|
||||
The scavenger system implements sophisticated conflict resolution strategies to handle inventory space limitations and complex storage scenarios.
|
||||
|
||||
#### Space Constraint Handling:
|
||||
|
||||
1. **Immediate Evaluation**: Before attempting item collection, the system evaluates current inventory state
|
||||
2. **Predictive Analysis**: Forecasts potential space conflicts based on incoming item characteristics
|
||||
3. **Proactive Organization**: Triggers organizer actions to create space before conflicts occur
|
||||
4. **Fallback Strategies**: Multiple contingency plans when primary storage options are unavailable
|
||||
|
||||
#### Complex Scenario Management:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Collecting : "Item detected"
|
||||
Collecting --> EvaluatingSpace : "Check inventory capacity"
|
||||
EvaluatingSpace --> SpaceAvailable : "Sufficient space found"
|
||||
EvaluatingSpace --> SpaceLimited : "Insufficient space"
|
||||
SpaceLimited --> AttemptOrganization : "Request organizer help"
|
||||
AttemptOrganization --> SpaceCreated : "Space made available"
|
||||
AttemptOrganization --> OrganizationFailed : "Cannot create space"
|
||||
SpaceCreated --> PlaceItem : "Place item in target location"
|
||||
SpaceAvailable --> PlaceItem
|
||||
PlaceItem --> CheckAutoEquip : "Evaluate auto-equip rules"
|
||||
CheckAutoEquip --> AutoEquipNeeded : "Equipment change required"
|
||||
CheckAutoEquip --> NoAction : "No additional action"
|
||||
AutoEquipNeeded --> CoordinateWithDress : "Request dress agent assistance"
|
||||
CoordinateWithDress --> EquipmentUpdated : "Equipment changed successfully"
|
||||
CoordinateWithDress --> EquipFailed : "Equipment change failed"
|
||||
EquipmentUpdated --> Complete : "Collection complete"
|
||||
NoAction --> Complete
|
||||
OrganizationFailed --> FallbackStrategy : "Try alternative approaches"
|
||||
FallbackStrategy --> DropLowPriority : "Drop lowest priority items"
|
||||
FallbackStrategy --> StoreElsewhere : "Use alternative storage"
|
||||
FallbackStrategy --> AbortCollection : "Abandon collection attempt"
|
||||
DropLowPriority --> PlaceItem
|
||||
StoreElsewhere --> PlaceItem
|
||||
EquipFailed --> PlaceItem
|
||||
AbortCollection --> Idle
|
||||
Complete --> Idle
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
### Integration with Organizer Agent
|
||||
|
||||
The scavenger system maintains tight integration with the Organizer agent to ensure efficient long-term storage management and optimal inventory organization.
|
||||
|
||||
#### Coordination Protocols:
|
||||
|
||||
1. **Real-Time Notifications**: Immediate notification when new items are collected
|
||||
2. **Batch Processing**: Grouping multiple items for efficient bulk organization
|
||||
3. **Priority Queuing**: Ensuring high-priority items receive immediate attention
|
||||
4. **Rule-Based Routing**: Applying organizer rules consistently across both systems
|
||||
|
||||
#### Storage Optimization Strategies:
|
||||
|
||||
- **Consolidation**: Combining similar items into efficient storage patterns
|
||||
- **Accessibility Planning**: Positioning frequently used items in easily accessible locations
|
||||
- **Resource Allocation**: Distributing items across multiple containers to prevent bottlenecks
|
||||
- **Dynamic Reorganization**: Adapting storage patterns based on usage patterns and changing needs
|
||||
|
||||
**Section sources**
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
|
||||
### Dress Agent Coordination
|
||||
|
||||
The scavenger system coordinates with the Dress agent to handle automatic equipment changes when collecting wearable items, ensuring optimal character configuration without manual intervention.
|
||||
|
||||
#### Equipment Change Workflow:
|
||||
|
||||
1. **Item Recognition**: Identifying wearable items during collection process
|
||||
2. **Suitability Assessment**: Evaluating whether new equipment improves current setup
|
||||
3. **Change Authorization**: Confirming equipment changes align with user preferences
|
||||
4. **Seamless Application**: Executing equipment swaps without disrupting gameplay flow
|
||||
|
||||
#### Smart Equipment Management:
|
||||
|
||||
- **Context-Aware Decisions**: Considering current combat situation and environment
|
||||
- **Progressive Upgrades**: Automatically equipping better items while preserving backups
|
||||
- **Set Preservation**: Maintaining complete equipment sets for different scenarios
|
||||
- **Manual Override Support**: Allowing user intervention when automatic decisions are inappropriate
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
|
||||
The scavenger system exhibits careful dependency management with clear separation of concerns and minimal coupling between components.
|
||||
|
||||
### Internal Dependencies:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Core Dependencies"
|
||||
SE["ScavengerEntry"] --> SM["ScavengerManager"]
|
||||
IT["Item"] --> SM
|
||||
PM["PlayerMobile"] --> SM
|
||||
end
|
||||
subgraph "External Agent Dependencies"
|
||||
OM["OrganizerManager"] -.-> SM
|
||||
DM["DressManager"] -.-> SM
|
||||
end
|
||||
subgraph "Network Dependencies"
|
||||
CCP["ContainerContentsPacket"] --> SM
|
||||
UOP["UO Packets"] --> CCP
|
||||
end
|
||||
subgraph "UI Dependencies"
|
||||
STV["ScavengerTabViewModel"] --> SM
|
||||
STC["ScavengerTabControl"] --> STV
|
||||
end
|
||||
SM --> SE
|
||||
SM --> IT
|
||||
SM --> PM
|
||||
SM --> CCP
|
||||
STV --> SM
|
||||
STC --> STV
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
|
||||
### Coupling Analysis:
|
||||
|
||||
- **Loose Coupling**: The scavenger manager uses interfaces rather than direct implementations for external agents
|
||||
- **Event-Driven Communication**: Reduces direct dependencies through publish-subscribe patterns
|
||||
- **Configuration-Based Behavior**: Minimizes hard-coded dependencies through flexible configuration systems
|
||||
- **Asynchronous Operations**: Prevents blocking dependencies through non-blocking communication patterns
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
The scavenger system is designed with performance optimization as a primary concern, implementing several strategies to minimize impact on game performance while providing responsive automation.
|
||||
|
||||
### Optimization Strategies:
|
||||
|
||||
1. **Efficient Item Scanning**: Optimized algorithms for rapid item detection and filtering
|
||||
2. **Memory Management**: Careful object pooling and garbage collection avoidance
|
||||
3. **Network Efficiency**: Batched packet processing and minimized network traffic
|
||||
4. **CPU Usage Control**: Adaptive processing rates based on system load and game activity
|
||||
5. **Concurrent Operations**: Parallel processing of independent tasks where possible
|
||||
|
||||
### Resource Utilization:
|
||||
|
||||
- **Memory Footprint**: Minimal memory allocation during normal operation
|
||||
- **Processing Cycles**: Intelligent throttling to prevent CPU contention
|
||||
- **Network Bandwidth**: Efficient packet compression and selective updates
|
||||
- **Storage I/O**: Buffered operations to reduce disk access frequency
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
Common issues and their resolutions when working with the scavenger agent system:
|
||||
|
||||
### Inventory Space Issues:
|
||||
- **Symptom**: Items not being collected despite having scavenger rules configured
|
||||
- **Cause**: Insufficient inventory space or container restrictions
|
||||
- **Resolution**: Enable organizer integration or configure larger storage containers
|
||||
|
||||
### Equipment Change Conflicts:
|
||||
- **Symptom**: Frequent unwanted equipment changes during scavenging
|
||||
- **Cause**: Overly aggressive auto-equip settings or conflicting dress agent rules
|
||||
- **Resolution**: Adjust auto-equip thresholds and review dress agent priorities
|
||||
|
||||
### Performance Degradation:
|
||||
- **Symptom**: Lag or stuttering during intensive scavenging sessions
|
||||
- **Cause**: Excessive item volume or inefficient storage organization
|
||||
- **Resolution**: Implement batch processing and optimize storage container distribution
|
||||
|
||||
### Integration Problems:
|
||||
- **Symptom**: Scavenger and organizer agents interfering with each other
|
||||
- **Cause**: Conflicting rules or timing issues in coordination protocols
|
||||
- **Resolution**: Review rule priorities and adjust processing intervals
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Scavenger Agent in ClassicAssist.Avalonia represents a sophisticated approach to automated inventory management in Ultima Online. Through its intelligent decision-making algorithms, robust conflict resolution mechanisms, and seamless integration with other automation agents, it provides players with powerful tools for managing large-scale resource collection and storage operations.
|
||||
|
||||
The system's modular architecture ensures maintainability and extensibility, while its performance optimizations guarantee smooth operation even under demanding conditions. The careful balance between automation and user control allows players to customize behavior to match their specific playstyles and preferences.
|
||||
|
||||
Future enhancements may include machine learning capabilities for adaptive storage optimization, enhanced predictive analytics for inventory planning, and expanded integration with community-driven storage solutions and sharing economies.
|
||||
+457
@@ -0,0 +1,457 @@
|
||||
# Optimization Strategies
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [Utility.cs](file://ClassicAssist.Shared/Misc/Utility.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 optimization strategies for the Scavenger Agent in ClassicAssist.Avalonia, focusing on efficient scanning across large map areas, distance-based prioritization, pathfinding considerations, and performance tuning for long automation sessions. It also covers power consumption considerations for mobile devices, advanced route planning, batch processing, multi-agent coordination, troubleshooting common issues (memory leaks, CPU spikes, network latency), and best practices for different environments and server conditions.
|
||||
|
||||
## Project Structure
|
||||
The Scavenger feature spans shared data models, UI view models, Avalonia views, tests, and core UO networking/data layers:
|
||||
- Data layer: Scavenger configuration entries and manager orchestration
|
||||
- UI layer: View model and tab control for configuring and monitoring scavengers
|
||||
- Core UO layer: Entity/item collections, map utilities, pathfinding packets, and packet queues
|
||||
- Tests: Validation of scavenger behavior and edge cases
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
SM["ScavengerManager.cs"]
|
||||
SE["ScavengerEntry.cs"]
|
||||
EC["EntityCollection.cs"]
|
||||
IC["ItemCollection.cs"]
|
||||
MP["Map.cs"]
|
||||
PF["Pathfind.cs"]
|
||||
TPQ["ThreadPriorityQueue.cs"]
|
||||
APQ["ActionPacketQueue.cs"]
|
||||
IPH["IncomingPacketHandlers.cs"]
|
||||
UT["Utility.cs"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
VM["ScavengerTabViewModel.cs"]
|
||||
TAB["ScavengerTabControl.axaml.cs"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
TST["ScavengerTests.cs"]
|
||||
end
|
||||
VM --> SM
|
||||
TAB --> VM
|
||||
SM --> EC
|
||||
SM --> IC
|
||||
SM --> MP
|
||||
SM --> PF
|
||||
SM --> TPQ
|
||||
SM --> APQ
|
||||
SM --> IPH
|
||||
SM --> UT
|
||||
TST --> SM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [Utility.cs](file://ClassicAssist.Shared/Misc/Utility.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [Utility.cs](file://ClassicAssist.Shared/Misc/Utility.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Core Components
|
||||
- ScavengerManager: Orchestrates scanning, prioritization, batching, and execution of scavenger tasks. Integrates with entity/item collections, map utilities, and pathfinding.
|
||||
- ScavengerEntry: Represents a single scavenger rule or target definition used by the manager to filter and prioritize items.
|
||||
- ScavengerTabViewModel: Exposes configuration and runtime state to the UI; coordinates user actions with the manager.
|
||||
- ScavengerTabControl.axaml.cs: Hosts the UI tab and binds to the view model.
|
||||
- EntityCollection/ItemCollection: Provide access to world entities and items, enabling selective loading and filtering.
|
||||
- Map: Supplies spatial utilities for distance calculations and region queries.
|
||||
- Pathfind: Encapsulates pathfinding packet interactions for movement planning.
|
||||
- ThreadPriorityQueue/ActionPacketQueue: Manage task scheduling and outgoing action pacing.
|
||||
- IncomingPacketHandlers: Update world state from server packets, affecting item/entity availability.
|
||||
- Utility: Common helpers for math, timing, and general operations.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [Utility.cs](file://ClassicAssist.Shared/Misc/Utility.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The Scavenger Agent follows a pipeline:
|
||||
- Configuration and rules are defined via ScavengerEntry and managed by ScavengerManager.
|
||||
- The UI (ScavengerTabViewModel + ScavengerTabControl) allows users to configure and monitor agents.
|
||||
- Scanning uses ItemCollection and EntityCollection filtered by ScavengerEntry criteria.
|
||||
- Distance-based prioritization leverages Map utilities to rank candidates.
|
||||
- Pathfinding uses Pathfind packets to plan routes around obstacles.
|
||||
- Execution is scheduled via ThreadPriorityQueue and ActionPacketQueue to pace actions and avoid flooding the server.
|
||||
- World updates come through IncomingPacketHandlers, keeping collections current.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "ScavengerTabViewModel"
|
||||
participant Tab as "ScavengerTabControl"
|
||||
participant Manager as "ScavengerManager"
|
||||
participant Items as "ItemCollection"
|
||||
participant Entities as "EntityCollection"
|
||||
participant Map as "Map"
|
||||
participant PF as "Pathfind"
|
||||
participant Queue as "ActionPacketQueue"
|
||||
participant Net as "IncomingPacketHandlers"
|
||||
UI->>Manager : Configure rules (ScavengerEntry[])
|
||||
Tab->>UI : User actions (start/stop/pause)
|
||||
Manager->>Items : Query items by filters
|
||||
Manager->>Entities : Query nearby entities if needed
|
||||
Manager->>Map : Compute distances and sort
|
||||
Manager->>PF : Request path to target
|
||||
PF-->>Manager : Path result
|
||||
Manager->>Queue : Enqueue pick/use/drop actions
|
||||
Net-->>Manager : Updates (items/entities change)
|
||||
Manager-->>UI : Progress and status updates
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### ScavengerManager
|
||||
Responsibilities:
|
||||
- Rule evaluation against item/entity collections
|
||||
- Distance-based prioritization using map utilities
|
||||
- Batch grouping of similar targets to reduce overhead
|
||||
- Scheduling via priority queue and action queue
|
||||
- Coordination with pathfinding and incoming updates
|
||||
|
||||
Optimization patterns:
|
||||
- Selective loading: Filter by type, hue, location before scoring
|
||||
- Spatial pruning: Use bounding boxes or radius checks to limit candidate sets
|
||||
- Priority scoring: Combine distance, rarity, and urgency into a single score
|
||||
- Batching: Group identical or similar items to minimize repeated pathfinding and packet bursts
|
||||
- Backoff and throttling: Pace actions to avoid server-side rate limits and reduce CPU/network spikes
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerManager {
|
||||
+configure(entries)
|
||||
+scan()
|
||||
+prioritize(candidates)
|
||||
+batch(targets)
|
||||
+schedule(actions)
|
||||
+updateFromPackets()
|
||||
}
|
||||
class ScavengerEntry {
|
||||
+type
|
||||
+hue
|
||||
+filters
|
||||
+priorityWeight
|
||||
}
|
||||
class ItemCollection
|
||||
class EntityCollection
|
||||
class Map
|
||||
class Pathfind
|
||||
class ActionPacketQueue
|
||||
class ThreadPriorityQueue
|
||||
ScavengerManager --> ScavengerEntry : "uses"
|
||||
ScavengerManager --> ItemCollection : "queries"
|
||||
ScavengerManager --> EntityCollection : "queries"
|
||||
ScavengerManager --> Map : "distance/radius"
|
||||
ScavengerManager --> Pathfind : "route planning"
|
||||
ScavengerManager --> ActionPacketQueue : "enqueues actions"
|
||||
ScavengerManager --> ThreadPriorityQueue : "task scheduling"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
### Scanning Algorithm and Prioritization
|
||||
Key steps:
|
||||
- Candidate selection: Apply ScavengerEntry filters to ItemCollection and optionally EntityCollection
|
||||
- Spatial pruning: Limit to a configurable radius around the player or waypoint
|
||||
- Scoring: Combine distance, rarity, and urgency weights
|
||||
- Sorting: Produce an ordered list of targets
|
||||
- Batching: Merge adjacent or identical targets to reduce redundant work
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Scan"]) --> LoadCandidates["Load candidates from ItemCollection<br/>and EntityCollection"]
|
||||
LoadCandidates --> ApplyFilters["Apply ScavengerEntry filters"]
|
||||
ApplyFilters --> SpatialPrune["Spatial prune by radius/bounds"]
|
||||
SpatialPrune --> ScoreTargets["Score targets (distance + weights)"]
|
||||
ScoreTargets --> SortTargets["Sort by score"]
|
||||
SortTargets --> BatchTargets["Batch similar/adjacent targets"]
|
||||
BatchTargets --> ScheduleActions["Schedule actions via queues"]
|
||||
ScheduleActions --> End(["End Scan"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
|
||||
### Pathfinding Integration
|
||||
- Uses Pathfind packets to compute routes to target locations
|
||||
- Considers obstacles and terrain flags via Map data
|
||||
- Replans when dynamic changes occur (e.g., new objects blocking paths)
|
||||
- Integrates with ActionPacketQueue to pace movement commands
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant M as "ScavengerManager"
|
||||
participant P as "Pathfind"
|
||||
participant Q as "ActionPacketQueue"
|
||||
M->>P : Request path to target
|
||||
P-->>M : Path nodes or failure
|
||||
alt Path found
|
||||
M->>Q : Enqueue move-to-node actions
|
||||
else No path
|
||||
M->>M : Fallback (wait/retry or skip)
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### UI and Configuration Flow
|
||||
- ScavengerTabViewModel exposes configuration properties and runtime state
|
||||
- ScavengerTabControl hosts the UI and forwards user actions to the view model
|
||||
- Changes propagate to ScavengerManager for immediate effect
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant Tab as "ScavengerTabControl"
|
||||
participant VM as "ScavengerTabViewModel"
|
||||
participant M as "ScavengerManager"
|
||||
User->>Tab : Adjust settings
|
||||
Tab->>VM : Update bound properties
|
||||
VM->>M : Apply configuration
|
||||
M-->>VM : Emit progress/status
|
||||
VM-->>Tab : Refresh UI
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### Testing and Validation
|
||||
- ScavengerTests validates key behaviors such as filtering, prioritization, and batching under various scenarios
|
||||
- Helps ensure stability and regression-free updates
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies:
|
||||
- ScavengerManager depends on ItemCollection, EntityCollection, Map, Pathfind, ActionPacketQueue, ThreadPriorityQueue, and IncomingPacketHandlers
|
||||
- UI components depend on ScavengerManager via ScavengerTabViewModel
|
||||
- Tests depend on ScavengerManager for behavioral validation
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
VM["ScavengerTabViewModel.cs"] --> M["ScavengerManager.cs"]
|
||||
TAB["ScavengerTabControl.axaml.cs"] --> VM
|
||||
M --> IC["ItemCollection.cs"]
|
||||
M --> EC["EntityCollection.cs"]
|
||||
M --> MAP["Map.cs"]
|
||||
M --> PF["Pathfind.cs"]
|
||||
M --> APQ["ActionPacketQueue.cs"]
|
||||
M --> TPQ["ThreadPriorityQueue.cs"]
|
||||
M --> IPH["IncomingPacketHandlers.cs"]
|
||||
TST["ScavengerTests.cs"] --> M
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.axaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Selective entity loading
|
||||
- Prefer targeted queries over full scans; use filters early to reduce candidate sets
|
||||
- Limit scan radius based on environment density and server load
|
||||
- Memory usage reduction
|
||||
- Avoid retaining references to transient items after processing
|
||||
- Reuse buffers and temporary lists where possible
|
||||
- Periodically compact or clear caches if applicable
|
||||
- CPU cycle management
|
||||
- Throttle scan frequency; adapt to FPS or tick rates
|
||||
- Use priority queues to process high-value targets first
|
||||
- Batch pathfinding requests and reuse computed paths when stable
|
||||
- Network efficiency
|
||||
- Coalesce actions into batches to reduce packet volume
|
||||
- Respect server rate limits; implement backoff on failures
|
||||
- Battery life optimization (mobile)
|
||||
- Reduce scan frequency and background activity when idle
|
||||
- Lower screen refresh and disable non-essential UI updates during automation
|
||||
- Prefer offline computations (scoring, sorting) over frequent network calls
|
||||
- Advanced strategies
|
||||
- Intelligent route planning: Plan multi-stop routes that minimize total travel distance
|
||||
- Batch processing: Group similar items (same type/hue) to amortize pathfinding and interaction costs
|
||||
- Multi-agent coordination: Share target assignments to avoid duplicate pickups and conflicts
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- High CPU usage
|
||||
- Reduce scan frequency and tighten filters
|
||||
- Increase batch sizes to lower per-item overhead
|
||||
- Profile hotspots in prioritization and pathfinding
|
||||
- Memory growth or leaks
|
||||
- Ensure temporary collections are cleared after each scan
|
||||
- Avoid holding long-lived references to items/mobs
|
||||
- Monitor collection sizes and reset when appropriate
|
||||
- Network latency spikes
|
||||
- Implement exponential backoff on failed actions
|
||||
- Stagger outgoing packets via ActionPacketQueue
|
||||
- Avoid excessive property queries; cache results when safe
|
||||
- Pathfinding failures
|
||||
- Retry with larger radii or alternate waypoints
|
||||
- Validate destination accessibility using Map data
|
||||
- Fall back to nearest valid tile if blocked
|
||||
- UI freezes
|
||||
- Offload heavy work off the UI thread
|
||||
- Debounce UI updates and coalesce state changes
|
||||
|
||||
**Section sources**
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
## Conclusion
|
||||
Effective Scavenger Agent optimization hinges on precise filtering, spatial pruning, intelligent prioritization, and careful batching. By integrating robust pathfinding, pacing actions through queues, and adapting to server and device constraints, you can achieve reliable, efficient automation across diverse environments. Continuous testing and monitoring help maintain performance and stability over extended sessions.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
- Best practices for configuration
|
||||
- Start with conservative scan radii and gradually expand
|
||||
- Tune priority weights to match your goals (speed vs. completeness)
|
||||
- Enable batching for dense areas; disable for sparse maps to reduce latency
|
||||
- Use multiple agents with partitioned regions to avoid contention
|
||||
- Server-specific tips
|
||||
- On high-population servers, increase throttling and batch sizes
|
||||
- On low-latency servers, reduce delays for snappier responses
|
||||
- For laggy connections, rely more on local caching and fewer round-trips
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
+352
@@ -0,0 +1,352 @@
|
||||
# Scavenger Agent
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
|
||||
## Introduction
|
||||
The Scavenger Agent automates resource collection by scanning the game world for specified items and moving to them for pickup or interaction. It supports configuration-driven item targeting, quantity tracking, and integrates with inventory management and container organization systems. The agent is designed to be efficient across large map areas, minimize battery usage on mobile devices, and coexist with other agents without conflicts.
|
||||
|
||||
## Project Structure
|
||||
The Scavenger feature spans shared data models, UI view models, Avalonia views, and tests:
|
||||
- Data layer: ScavengerEntry and ScavengerManager define configuration and orchestration logic.
|
||||
- UI layer: ScavengerTabViewModel binds configuration to the UI; ScavengerTabControl hosts the tab.
|
||||
- Game object model: Item and ItemCollection provide access to world items.
|
||||
- Integration: OrganizerManager and OrganizerEntry coordinate container organization after scavenging.
|
||||
- Tests: ScavengerTests validate behavior and edge cases.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
SE["ScavengerEntry"]
|
||||
SM["ScavengerManager"]
|
||||
OM["OrganizerManager"]
|
||||
OE["OrganizerEntry"]
|
||||
IC["ItemCollection"]
|
||||
IT["Item"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
VM["ScavengerTabViewModel"]
|
||||
TC["ScavengerTabControl"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
ST["ScavengerTests"]
|
||||
end
|
||||
VM --> SE
|
||||
VM --> SM
|
||||
SM --> IC
|
||||
SM --> IT
|
||||
SM --> OM
|
||||
OM --> OE
|
||||
TC --> VM
|
||||
ST --> SM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
|
||||
## Core Components
|
||||
- ScavengerEntry: Represents a single scavenging rule (item type filter, quantity target, optional constraints).
|
||||
- ScavengerManager: Orchestrates scanning, selection, movement, and collection actions based on active entries.
|
||||
- ScavengerTabViewModel: Exposes configuration to the UI and updates state as the agent runs.
|
||||
- ScavengerTabControl: Hosts the UI tab for managing Scavenger rules.
|
||||
- Item and ItemCollection: Provide access to world objects and filtering capabilities used by the scanner.
|
||||
- OrganizerManager and OrganizerEntry: Coordinate post-collection organization into containers.
|
||||
|
||||
Key responsibilities:
|
||||
- Configuration parsing and validation for ScavengerEntry.
|
||||
- World scanning using filters derived from ScavengerEntry.
|
||||
- Decision-making when multiple matches exist (e.g., nearest, highest stack).
|
||||
- Quantity tracking per entry and completion signaling.
|
||||
- Integration with Organizer to sort collected items.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The Scavenger Agent follows a clear separation between configuration, orchestration, and UI:
|
||||
- Configuration: ScavengerEntry defines what to collect and how much.
|
||||
- Orchestration: ScavengerManager reads configuration, scans ItemCollection, selects targets, and coordinates actions.
|
||||
- UI: ScavengerTabViewModel exposes properties and commands to the ScavengerTabControl.
|
||||
- Integration: After collection, OrganizerManager applies OrganizerEntry rules to place items into appropriate containers.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UI as "ScavengerTabControl"
|
||||
participant VM as "ScavengerTabViewModel"
|
||||
participant Mgr as "ScavengerManager"
|
||||
participant World as "ItemCollection"
|
||||
participant Org as "OrganizerManager"
|
||||
User->>UI : Open Scavenger Tab
|
||||
UI->>VM : Load/Bind Entries
|
||||
User->>VM : Start Agent
|
||||
VM->>Mgr : Run loop with entries
|
||||
loop For each entry
|
||||
Mgr->>World : Filter items by type/constraints
|
||||
Mgr->>Mgr : Select best match (nearest/stack)
|
||||
Mgr->>World : Move to target and interact/pickup
|
||||
Mgr->>Org : Organize collected items
|
||||
Mgr->>VM : Update progress/counts
|
||||
end
|
||||
VM-->>User : Completion status
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### ScavengerEntry
|
||||
Purpose:
|
||||
- Defines a single scavenging rule including item type filtering and quantity targets.
|
||||
- May include additional constraints such as hue, quality, or location-based filters.
|
||||
|
||||
Key aspects:
|
||||
- Item type filtering: Uses identifiers or categories to match world items.
|
||||
- Quantity tracking: Maintains required amount and current progress.
|
||||
- Constraints: Optional attributes that refine matching beyond base type.
|
||||
|
||||
Complexity considerations:
|
||||
- Filtering performance depends on the number of active entries and world item count.
|
||||
- Prefer specific filters to reduce candidate set size.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
### ScavengerManager
|
||||
Purpose:
|
||||
- Central orchestrator for scanning, selection, movement, and collection.
|
||||
- Manages lifecycle of the scavenging loop and communicates with UI via the ViewModel.
|
||||
|
||||
Core workflow:
|
||||
- Initialize with active ScavengerEntry list.
|
||||
- Iterate through entries until all quantities are satisfied.
|
||||
- For each entry:
|
||||
- Query ItemCollection with filters derived from the entry.
|
||||
- Apply selection criteria when multiple matches exist.
|
||||
- Execute movement and interaction to acquire the item.
|
||||
- Update quantity counters and notify UI.
|
||||
- Optionally delegate to OrganizerManager for sorting.
|
||||
|
||||
Selection algorithm:
|
||||
- When multiple candidates match, choose the most efficient target:
|
||||
- Nearest distance to player.
|
||||
- Highest stack size if applicable.
|
||||
- Accessibility constraints (e.g., not locked or blocked).
|
||||
|
||||
Integration points:
|
||||
- ItemCollection for world item enumeration and filtering.
|
||||
- OrganizerManager for post-collection organization.
|
||||
- ScavengerTabViewModel for progress reporting and control.
|
||||
|
||||
Error handling:
|
||||
- Graceful recovery when targets disappear or become unreachable.
|
||||
- Logging and UI feedback for failures.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
|
||||
### ScavengerTabViewModel and ScavengerTabControl
|
||||
Purpose:
|
||||
- ViewModel exposes configuration and runtime state to the UI.
|
||||
- View hosts controls for adding/removing entries, starting/stopping the agent, and viewing progress.
|
||||
|
||||
Responsibilities:
|
||||
- Bind ScavengerEntry collections to UI lists.
|
||||
- Handle user actions (start, stop, edit entries).
|
||||
- Update UI elements as ScavengerManager reports progress.
|
||||
|
||||
Interaction flow:
|
||||
- User opens ScavengerTabControl.
|
||||
- ViewModel loads entries and displays them.
|
||||
- User starts agent; ViewModel invokes ScavengerManager.
|
||||
- Manager updates counts; ViewModel refreshes UI.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
|
||||
### Integration with Organizer
|
||||
After collecting items, the Scavenger Agent can organize them into containers according to OrganizerEntry rules. This ensures consistent storage and reduces manual sorting.
|
||||
|
||||
Workflow:
|
||||
- Upon successful acquisition, pass items to OrganizerManager.
|
||||
- OrganizerManager evaluates OrganizerEntry rules to determine destination containers.
|
||||
- Items are moved accordingly.
|
||||
|
||||
**Section sources**
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
- [OrganizerEntry.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerEntry.cs)
|
||||
|
||||
### Algorithm Flowchart: Target Selection
|
||||
This flowchart illustrates decision-making when multiple items match an entry’s criteria.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Selection"]) --> Filter["Filter Items by Entry Criteria"]
|
||||
Filter --> Candidates{"Any Candidates?"}
|
||||
Candidates --> |No| Skip["Skip Entry Until New Items Appear"]
|
||||
Candidates --> |Yes| Sort["Sort by Distance and Stack Size"]
|
||||
Sort --> Pick["Pick Best Candidate"]
|
||||
Pick --> Interact["Move to Target and Interact/Pickup"]
|
||||
Interact --> Update["Update Quantity Counters"]
|
||||
Update --> Done(["Done"])
|
||||
Skip --> Done
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The Scavenger system has well-defined dependencies:
|
||||
- ScavengerManager depends on ItemCollection for world scanning and OrganizerManager for post-collection tasks.
|
||||
- ScavengerTabViewModel depends on ScavengerManager and ScavengerEntry for binding and control.
|
||||
- ScavengerTabControl depends on ScavengerTabViewModel for UI composition.
|
||||
- Tests depend on ScavengerManager to validate behavior.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerEntry {
|
||||
+filters
|
||||
+quantityTarget
|
||||
+constraints
|
||||
}
|
||||
class ScavengerManager {
|
||||
+run(entries)
|
||||
+scan()
|
||||
+selectBest()
|
||||
+interact(target)
|
||||
+updateProgress()
|
||||
}
|
||||
class ScavengerTabViewModel {
|
||||
+entries
|
||||
+start()
|
||||
+stop()
|
||||
+progress
|
||||
}
|
||||
class ScavengerTabControl {
|
||||
+bind(vm)
|
||||
}
|
||||
class ItemCollection {
|
||||
+filter(criteria)
|
||||
}
|
||||
class OrganizerManager {
|
||||
+organize(items)
|
||||
}
|
||||
ScavengerManager --> ScavengerEntry : "uses"
|
||||
ScavengerManager --> ItemCollection : "scans"
|
||||
ScavengerManager --> OrganizerManager : "organizes"
|
||||
ScavengerTabViewModel --> ScavengerManager : "controls"
|
||||
ScavengerTabControl --> ScavengerTabViewModel : "binds"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
|
||||
- [ItemCollection.cs](file://ClassicAssist.Shared/UO/Objects/ItemCollection.cs)
|
||||
- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Large map areas:
|
||||
- Use precise filters in ScavengerEntry to reduce candidate sets.
|
||||
- Prefer nearest-first selection to minimize movement overhead.
|
||||
- Battery life optimization:
|
||||
- Avoid excessive polling; rely on event-driven updates where possible.
|
||||
- Batch interactions and avoid redundant path recalculations.
|
||||
- Conflict resolution with other agents:
|
||||
- Ensure non-blocking operations so other agents can run concurrently.
|
||||
- Respect locks and ownership to prevent collisions.
|
||||
- Memory and CPU:
|
||||
- Reuse filter instances and avoid creating temporary collections unnecessarily.
|
||||
- Debounce UI updates to prevent heavy redraws.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- No items found:
|
||||
- Verify ScavengerEntry filters match actual item types in the area.
|
||||
- Check constraints (hue, quality) that may exclude valid items.
|
||||
- Multiple matches causing wrong picks:
|
||||
- Adjust selection criteria to prioritize nearest or largest stacks.
|
||||
- Confirm accessibility flags are correct.
|
||||
- Stuck or slow performance:
|
||||
- Reduce number of active entries.
|
||||
- Narrow filters to relevant regions or item categories.
|
||||
- Organization failures:
|
||||
- Validate OrganizerEntry rules for destination containers.
|
||||
- Ensure sufficient space in target containers.
|
||||
|
||||
Validation references:
|
||||
- Unit tests cover typical scenarios and edge cases for the Scavenger Agent.
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Conclusion
|
||||
The Scavenger Agent provides a robust, configurable system for automated resource collection. With clear separation between configuration, orchestration, and UI, it integrates seamlessly with inventory and organization tools. By applying targeted filters, efficient selection algorithms, and careful performance tuning, it scales well across large maps and coexists with other agents.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
+335
@@ -0,0 +1,335 @@
|
||||
# Scavenger Fundamentals
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
</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 fundamentals of the Scavenger Agent in ClassicAssist.Avalonia. It focuses on how automated resource gathering is configured and executed, including:
|
||||
- How ScavengerEntry configurations define target items, quantities, and collection priorities
|
||||
- The item type filtering system for categories such as ores, logs, herbs, or general loot
|
||||
- The quantity tracking mechanism that monitors collected items and determines when targets are met
|
||||
- Practical examples for common scenarios like mining copper ore, collecting wood from trees, or harvesting herbs
|
||||
- The relationship between scavenger entries and the game’s item identification system
|
||||
|
||||
The goal is to provide both conceptual understanding and practical guidance for setting up and using the Scavenger Agent effectively.
|
||||
|
||||
## Project Structure
|
||||
The Scavenger feature spans shared data models, UI view models, Avalonia views, and tests. Key locations include:
|
||||
- Data model and manager for Scavenger entries and lifecycle
|
||||
- UI view model binding the configuration to the UI
|
||||
- Avalonia tab control hosting the Scavenger UI
|
||||
- Tests validating behavior and edge cases
|
||||
- Core UO object abstractions used by the agent (items and collections)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Data"
|
||||
SE["ScavengerEntry.cs"]
|
||||
SM["ScavengerManager.cs"]
|
||||
end
|
||||
subgraph "UI Layer"
|
||||
VM["ScavengerTabViewModel.cs"]
|
||||
TAB["ScavengerTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "UO Objects"
|
||||
ITEM["Item.cs"]
|
||||
COL["EntityCollection.cs"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
TST["ScavengerTests.cs"]
|
||||
end
|
||||
VM --> SE
|
||||
VM --> SM
|
||||
TAB --> VM
|
||||
SM --> ITEM
|
||||
SM --> COL
|
||||
TST --> SM
|
||||
TST --> SE
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Core Components
|
||||
- ScavengerEntry: Defines a single scavenging target with properties for item identification, quantity goals, and priority.
|
||||
- ScavengerManager: Orchestrates scanning, matching, prioritization, and execution of actions against world items based on active entries.
|
||||
- ScavengerTabViewModel: Binds Scavenger configuration to the UI, exposes commands, and updates counts/status.
|
||||
- ScavengerTabControl: Hosts the Scavenger UI within the Avalonia interface.
|
||||
- Item and EntityCollection: Provide access to in-game items and collections used by the manager to locate and interact with resources.
|
||||
|
||||
Key responsibilities:
|
||||
- Entry configuration: item IDs, names, types, quantities, and priorities
|
||||
- Filtering: category-based selection (ores, logs, herbs, general loot)
|
||||
- Tracking: maintain current counts per entry and determine completion
|
||||
- Execution: select best candidate based on priority and proximity, then perform targeted interactions
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The Scavenger Agent follows a layered architecture:
|
||||
- Configuration layer: ScavengerEntry defines what to collect and how important it is
|
||||
- Orchestration layer: ScavengerManager scans entities, filters matches, tracks progress, and selects next action
|
||||
- UI layer: ScavengerTabViewModel and ScavengerTabControl present configuration and status
|
||||
- Game integration: Item and EntityCollection expose live world state
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UI as "ScavengerTabControl"
|
||||
participant VM as "ScavengerTabViewModel"
|
||||
participant Mgr as "ScavengerManager"
|
||||
participant World as "EntityCollection"
|
||||
participant Item as "Item"
|
||||
User->>UI : Open Scavenger Tab
|
||||
UI->>VM : Initialize bindings
|
||||
VM->>Mgr : Load entries and start monitoring
|
||||
loop Each tick
|
||||
Mgr->>World : Enumerate visible items
|
||||
World-->>Mgr : Items[]
|
||||
Mgr->>Mgr : Filter by entries (type/category)
|
||||
Mgr->>Mgr : Update counts and priorities
|
||||
alt Target not met
|
||||
Mgr->>Mgr : Select best candidate
|
||||
Mgr->>Item : Interact (target/use/skill)
|
||||
else Target met
|
||||
Mgr->>Mgr : Mark entry complete
|
||||
end
|
||||
VM->>Mgr : Refresh status and counts
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### ScavengerEntry: Target Definition
|
||||
ScavengerEntry encapsulates a single resource target. Typical fields include:
|
||||
- Identification: item ID(s), name patterns, and/or type/category
|
||||
- Quantity: desired amount to collect
|
||||
- Priority: relative importance among multiple entries
|
||||
- Flags: optional constraints (e.g., only certain hues or conditions)
|
||||
|
||||
Behavioral notes:
|
||||
- Multiple identifiers can be specified to match variants of an item
|
||||
- Category filters allow broad targeting (ores, logs, herbs, general loot)
|
||||
- Priority influences selection order when multiple candidates exist
|
||||
|
||||
Practical setup examples:
|
||||
- Mining copper ore: set entry to copper ore ID/type with desired quantity; assign higher priority if you want to focus on copper first
|
||||
- Collecting wood from trees: configure entry for log type or tree-related statics; ensure category filter includes logs
|
||||
- Harvesting herbs: configure entry for herb types; optionally add hue constraints if needed
|
||||
|
||||
Relationship to item identification:
|
||||
- Entries rely on item IDs and types exposed by the game’s item system
|
||||
- Matching uses these identifiers to find suitable world objects
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
### ScavengerManager: Orchestration and Tracking
|
||||
ScavengerManager coordinates the entire scavenging process:
|
||||
- Scanning: enumerates nearby or visible items via EntityCollection
|
||||
- Filtering: applies entry criteria (IDs, types, categories) to build candidate lists
|
||||
- Prioritization: selects the most relevant candidate based on entry priority and other factors
|
||||
- Tracking: maintains per-entry counts and determines when targets are met
|
||||
- Execution: performs actions such as targeting or using skills to gather resources
|
||||
|
||||
Algorithm overview:
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Tick"]) --> Scan["Enumerate Items<br/>from EntityCollection"]
|
||||
Scan --> BuildCandidates["Build Candidates per Entry<br/>by ID/Type/Category"]
|
||||
BuildCandidates --> UpdateCounts["Update Collected Counts"]
|
||||
UpdateCounts --> CheckTargets{"Any Targets Met?"}
|
||||
CheckTargets --> |Yes| MarkComplete["Mark Entry Complete"]
|
||||
CheckTargets --> |No| SelectCandidate["Select Best Candidate<br/>by Priority and Proximity"]
|
||||
SelectCandidate --> ExecuteAction["Target/Use/Skill to Gather"]
|
||||
ExecuteAction --> End(["End Tick"])
|
||||
MarkComplete --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
|
||||
### UI Integration: ScavengerTabViewModel and ScavengerTabControl
|
||||
- ScavengerTabViewModel binds ScavengerEntry collections to the UI, exposes commands to add/remove/edit entries, and refreshes counts/status
|
||||
- ScavengerTabControl hosts the UI and initializes the view model
|
||||
|
||||
User workflow:
|
||||
- Add new entries with item identifiers and target quantities
|
||||
- Adjust priorities to influence collection order
|
||||
- Observe real-time counts and completion status
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
|
||||
### Item Identification System Integration
|
||||
Scavenger relies on the game’s item identification system:
|
||||
- Item IDs and types are primary matching keys
|
||||
- Categories (ores, logs, herbs, general loot) map to item type groups
|
||||
- Hue and property filters may refine matches where supported
|
||||
|
||||
This ensures accurate targeting across different shard implementations and item sets.
|
||||
|
||||
**Section sources**
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
### Example Scenarios
|
||||
|
||||
#### Basic Setup: Mining Copper Ore
|
||||
- Create a ScavengerEntry for copper ore using its ID/type
|
||||
- Set target quantity to your inventory capacity or desired amount
|
||||
- Assign high priority to focus on copper before other materials
|
||||
- Ensure category filter includes ores
|
||||
|
||||
#### Basic Setup: Collecting Wood from Trees
|
||||
- Configure entry for logs or tree-related statics
|
||||
- Use category filter for logs
|
||||
- Set quantity based on crafting needs
|
||||
- Lower priority than ores if you prefer to mine first
|
||||
|
||||
#### Basic Setup: Harvesting Herbs
|
||||
- Configure entry for herb types
|
||||
- Optionally constrain by hue if specific herb colors matter
|
||||
- Set quantity and moderate priority
|
||||
|
||||
These examples demonstrate how entries translate into automated collection workflows.
|
||||
|
||||
[No sources needed since this section provides conceptual examples without analyzing specific files]
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram shows key dependencies among Scavenger components and core UO abstractions:
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerEntry {
|
||||
+Identifier
|
||||
+Quantity
|
||||
+Priority
|
||||
+CategoryFilter
|
||||
}
|
||||
class ScavengerManager {
|
||||
+Scan()
|
||||
+Filter()
|
||||
+Prioritize()
|
||||
+TrackCounts()
|
||||
+Execute()
|
||||
}
|
||||
class ScavengerTabViewModel {
|
||||
+Entries
|
||||
+Refresh()
|
||||
+AddEntry()
|
||||
+RemoveEntry()
|
||||
}
|
||||
class ScavengerTabControl {
|
||||
+InitializeBindings()
|
||||
}
|
||||
class Item {
|
||||
+ID
|
||||
+Type
|
||||
+Hue
|
||||
}
|
||||
class EntityCollection {
|
||||
+Enumerate()
|
||||
}
|
||||
ScavengerTabViewModel --> ScavengerEntry : "manages"
|
||||
ScavengerTabViewModel --> ScavengerManager : "delegates"
|
||||
ScavengerTabControl --> ScavengerTabViewModel : "hosts"
|
||||
ScavengerManager --> ScavengerEntry : "evaluates"
|
||||
ScavengerManager --> EntityCollection : "reads"
|
||||
ScavengerManager --> Item : "targets"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Limit scan scope: Prefer local or filtered enumeration to reduce overhead
|
||||
- Batch updates: Avoid excessive UI refreshes; coalesce count updates
|
||||
- Prioritize efficiently: Precompute candidate lists per entry to minimize repeated filtering
|
||||
- Throttle actions: Prevent spamming target/use calls; respect cooldowns and server limits
|
||||
- Cache stable data: Reuse item metadata where possible to avoid redundant lookups
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- No matches found: Verify item IDs/types and category filters align with the shard’s item definitions
|
||||
- Incorrect priority ordering: Adjust entry priorities to reflect desired collection sequence
|
||||
- Count not updating: Ensure the manager is running and the UI is refreshing; check for errors in the manager loop
|
||||
- Excessive targeting: Reduce scan frequency or increase minimum distance thresholds to avoid over-targeting
|
||||
|
||||
Validation references:
|
||||
- Unit tests cover typical behaviors and edge cases for Scavenger functionality
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)
|
||||
|
||||
## Conclusion
|
||||
The Scavenger Agent in ClassicAssist.Avalonia provides a flexible and powerful framework for automated resource gathering. By configuring ScavengerEntry targets, leveraging category filters, and managing priorities, players can automate tasks such as mining ores, collecting wood, and harvesting herbs. The ScavengerManager orchestrates scanning, filtering, tracking, and execution, while the UI layers offer intuitive configuration and real-time feedback. Proper alignment with the game’s item identification system ensures reliable matching across different environments.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
Reference in New Issue
Block a user