# 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.