beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Beyhan Oğur
2026-09-03 04:45:36 +03:00
commit d5f52cc3d3
1038 changed files with 169579 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/en/content/Game Automation Features/Scavenger Agent/Scavenger Fundamentals.md
+335
View File
@@ -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]