# 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)
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
- [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)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.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)
10. [Appendices](#appendices)

## Introduction
The Scavenger agent automates resource gathering and inventory management by continuously scanning the game world for items that match user-defined rules, moving to those items, targeting them, and collecting them into containers or the player’s backpack. It supports prioritization, conflict resolution when multiple scavengers target the same item, and integrates with movement and pathfinding systems to optimize travel. The UI allows users to create and manage scavenging profiles, configure collection priorities, and monitor activity.

## Project Structure
The Scavenger feature spans data models, managers, UI view models, and tests:
- Data layer defines entries and manager logic for scavenging rules and lifecycle.
- UI layer provides a tabbed interface for managing entries and monitoring status.
- Integration points connect to item discovery, targeting, movement, and container updates.

```mermaid
graph TB
subgraph "Shared Data"
SE["ScavengerEntry.cs"]
SM["ScavengerManager.cs"]
end
subgraph "UI (Avalonia)"
VM["ScavengerTabViewModel.cs"]
XAML["ScavengerTabControl.xaml(.cs)"]
end
subgraph "Game Objects"
ITEM["Item.cs"]
EC["EntityCollection.cs"]
end
subgraph "Integration"
TM["TargetManager.cs"]
MC["MovementCommands.cs"]
CCP["ContainerContentsPacket.cs"]
end
VM --> SM
XAML --> VM
SM --> SE
SM --> EC
SM --> ITEM
SM --> TM
SM --> MC
SM --> CCP
```

**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)
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.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)
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)

## Core Components
- ScavengerEntry: Represents a single scavenging rule including target identification criteria, priority, and behavior flags.
- ScavengerManager: Orchestrates scanning, selection, routing, targeting, and collection; manages conflicts and state across entries.
- ScavengerTabViewModel: Binds UI to manager operations, exposes collections and commands for adding/removing/editing entries and toggling activity.
- ScavengerTabControl: Avalonia UI control hosting the tab content and binding to the view model.

Key responsibilities:
- Rule evaluation against visible items.
- Priority-based selection among candidates.
- Movement and pathfinding integration to reach targets.
- Targeting and interaction to collect items.
- Inventory awareness to avoid overfilling and to route items to appropriate containers.

**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)

## Architecture Overview
The Scavenger system follows a layered architecture:
- UI Layer: Tab control and view model expose configuration and monitoring.
- Manager Layer: Centralized orchestration of scanning, selection, movement, targeting, and collection.
- Game Object Layer: Item and entity collections provide real-time world state.
- Integration Layer: Targeting and movement subsystems execute actions on the client.

```mermaid
sequenceDiagram
participant UI as "ScavengerTabControl"
participant VM as "ScavengerTabViewModel"
participant Mgr as "ScavengerManager"
participant World as "EntityCollection/Item"
participant Move as "MovementCommands"
participant Tgt as "TargetManager"
participant Inv as "ContainerContentsPacket"
UI->>VM : Load profile / toggle active
VM->>Mgr : Start/Stop, Add/Remove Entry
loop Scan Cycle
Mgr->>World : Query visible items
Mgr->>Mgr : Evaluate rules and priorities
Mgr->>Move : Request move to target
Move-->>Mgr : Movement status
Mgr->>Tgt : Target item
Tgt-->>Mgr : Target result
Mgr->>Mgr : Attempt pickup/collection
Inv-->>Mgr : Container update events
Mgr->>Mgr : Update state and logs
end
```

**Diagram sources**
- [ScavengerTabControl.xaml.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)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)

## Detailed Component Analysis

### ScavengerEntry
Purpose:
- Encapsulates a single scavenging rule with fields for target identification (e.g., item ID, properties), priority, and optional constraints (such as quantity thresholds or conditions).
- Provides helpers to evaluate whether an item matches the entry’s criteria.

Design considerations:
- Immutable or value-like semantics are preferred for rule stability during comparisons.
- Matching logic should be efficient to support large item sets.

Usage examples:
- Material gathering: Define entries for ore types with specific hues or names.
- Crafting resources: Match items by property patterns or categories.
- Valuable items: High-priority entries for rare loot.

**Section sources**
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)

### ScavengerManager
Responsibilities:
- Maintains a list of ScavengerEntry instances.
- Periodically scans EntityCollection for matching items.
- Resolves conflicts when multiple entries target the same item using priority and last-seen timestamps.
- Coordinates movement via MovementCommands and targeting via TargetManager.
- Monitors inventory changes through container packet handlers to adapt collection strategies.

Algorithm highlights:
- Candidate generation: Filter visible items by each entry’s matching function.
- Conflict resolution: For overlapping candidates, select the highest priority entry; break ties with recency or distance heuristics.
- Routing: Prefer nearby targets to minimize travel time; consider obstacles implicitly via movement commands.
- Collection: After reaching proximity, target and attempt pickup; handle failures gracefully and retry if needed.

State and observability:
- Exposes current activity status, last action, and counts of matched/targeted items.
- Emits events or notifications consumed by the UI for live feedback.

**Section sources**
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)

### ScavengerTabViewModel
Role:
- Bridges UI interactions to ScavengerManager.
- Manages observable collections of entries and exposes commands for add/remove/edit/toggle.
- Displays status indicators and recent activity logs.

User workflows:
- Create new entries by selecting item identifiers and setting priority.
- Reorder entries to adjust global precedence.
- Enable/disable individual entries or the entire scavenger session.

**Section sources**
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)

### ScavengerTabControl (Avalonia)
Role:
- Hosts the Scavenger tab UI, binds to ScavengerTabViewModel, and renders lists, forms, and status panels.
- Ensures thread-safe updates from background manager operations.

**Section sources**
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)

### Example Profiles
- Materials: Entries for common ores with moderate priority; lower priority for rarer variants.
- Crafting Resources: Entries for herbs, leather, and reagents with medium priority; include property filters for quality if available.
- Valuables: High-priority entries for gems or unique items; ensure they do not block essential resource collection by balancing priorities.

[No sources needed since this section provides conceptual examples]

## Dependency Analysis
High-level dependencies:
- ScavengerManager depends on:
  - ScavengerEntry for rule definitions.
  - EntityCollection and Item for world state.
  - MovementCommands for navigation.
  - TargetManager for targeting actions.
  - ContainerContentsPacket for inventory updates.
- UI components depend on ScavengerTabViewModel, which delegates to ScavengerManager.

```mermaid
classDiagram
class ScavengerEntry {
+Match(item) bool
+Priority int
}
class ScavengerManager {
+Start()
+Stop()
+AddEntry(entry)
+RemoveEntry(id)
-SelectCandidate()
-ResolveConflicts(candidates)
-RouteTo(target)
-Collect(target)
}
class ScavengerTabViewModel {
+Entries ObservableCollection
+IsActive bool
+Start()
+Stop()
}
class EntityCollection
class Item
class MovementCommands
class TargetManager
class ContainerContentsPacket
ScavengerManager --> ScavengerEntry : "uses"
ScavengerManager --> EntityCollection : "queries"
ScavengerManager --> Item : "evaluates"
ScavengerManager --> MovementCommands : "moves"
ScavengerManager --> TargetManager : "targets"
ScavengerManager --> ContainerContentsPacket : "listens"
ScavengerTabViewModel --> ScavengerManager : "delegates"
```

**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)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.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)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)

## Performance Considerations
- Efficient filtering: Keep ScavengerEntry matching logic lightweight; precompute stable attributes where possible.
- Batched scanning: Avoid excessive polling; use event-driven updates from entity and container packets.
- Intelligent routing: Prefer nearest targets and batch pickups along a path to reduce movement overhead.
- Conflict resolution: Use priority and recency to minimize contention; avoid redundant targeting attempts.
- Memory usage: Limit retained candidate lists; clear stale entries promptly.
- Threading: Ensure UI updates are marshaled correctly; keep heavy work off the UI thread.

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- Items not collected: Verify visibility range and line-of-sight; check movement success logs; confirm targeting succeeded.
- Conflicting entries: Adjust priorities so high-value items do not starve essential resources; review tie-breaking behavior.
- Inventory full: Configure fallback behaviors such as dropping low-priority items or switching containers; monitor container updates.
- Stuck movement: Inspect movement command responses; ensure pathfinding is functional and no obstacles block routes.
- UI lag: Reduce number of active entries; throttle scan frequency; ensure background tasks are not blocking UI.

Validation references:
- Unit tests cover core behaviors and edge cases for scavenger logic.

**Section sources**
- [ScavengerTests.cs](file://ClassicAssist.Tests/Agents/ScavengerTests.cs)

## Conclusion
The Scavenger agent provides a robust, configurable automation layer for resource gathering and inventory management. By combining precise rule definitions, intelligent routing, and strong integration with movement and targeting systems, it delivers reliable performance even in large areas. Properly configured profiles and priorities enable balanced collection strategies across materials, crafting resources, and valuables.

[No sources needed since this section summarizes without analyzing specific files]

## Appendices

### Creating Scavenger Profiles
- Identify target items by ID, name, hue, or properties.
- Assign priorities reflecting importance.
- Group related items into cohesive profiles for different activities (mining, herbalism, looting).

[No sources needed since this section provides conceptual guidance]

### Monitoring Activity
- Use the Scavenger tab to observe active entries, recent actions, and status indicators.
- Review logs for failed movements or targeting attempts to refine rules and priorities.

**Section sources**
- [ScavengerTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml.cs)
- [ScavengerTabControl.xaml](file://ClassicAssist.Avalonia/Views/Agents/ScavengerTabControl.axaml)
- [ScavengerTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/ScavengerTabViewModel.cs)