first commit
This commit is contained in:
Beyhan Oğur
+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]
|
||||
Reference in New Issue
Block a user