Beyhan Oğur
17 KiB
Agent Framework
**Referenced Files in This Document** - [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs) - [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs) - [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs) - [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs) - [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs) - [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs) - [PropertyEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/PropertyEntry.cs) - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [Engine.cs](file://ClassicAssist.Shared/Engine.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
The ClassicAssist.Avalonia agent framework provides a sophisticated automation system for Ultima Online gameplay through a modular agent architecture. This framework enables players to create intelligent agents that can automatically perform various tasks such as loot collection, equipment management, item scavenging, and vendor operations. The framework is built around a rule-based engine that evaluates conditions and executes actions based on game state and player-defined rules.
The agent system follows a manager-based pattern where each type of automated behavior is encapsulated in its own manager class, providing clear separation of concerns and making it easy to extend functionality with custom agents.
Project Structure
The agent framework is primarily implemented within the ClassicAssist.Shared project, with UI components distributed across both ClassicAssist (WPF) and ClassicAssist.Avalonia projects. The core architecture consists of:
graph TB
subgraph "Agent Framework Core"
Engine[Engine]
ManagerBase[Manager Base Class]
RuleEngine[Rule Engine]
ConditionEvaluator[Condition Evaluator]
ActionExecutor[Action Executor]
end
subgraph "Built-in Agents"
Autoloot[AUTOLootManager]
Dress[DressManager]
Scavenger[ScavengerManager]
VendorBuy[VendorBuyManager]
VendorSell[VendorSellManager]
Organizer[OrganizerManager]
end
subgraph "Data Models"
EntryModels[Entry Models]
PropertySystem[Property System]
FilterSystem[Filter System]
end
subgraph "UI Layer"
WPFUI[WPF UI]
AvaloniaUI[Avalonia UI]
ViewModels[ViewModels]
end
Engine --> ManagerBase
ManagerBase --> RuleEngine
RuleEngine --> ConditionEvaluator
RuleEngine --> ActionExecutor
Autoloot --> ManagerBase
Dress --> ManagerBase
Scavenger --> ManagerBase
ManagerBase --> EntryModels
EntryModels --> PropertySystem
EntryModels --> FilterSystem
WPFUI --> ViewModels
AvaloniaUI --> ViewModels
Diagram sources
Core Components
Agent Architecture Pattern
The agent framework implements a manager-based architecture where each specialized agent type extends a common base class. This pattern provides:
- Lifecycle Management: Standardized initialization, update, and cleanup processes
- Event Handling: Consistent event processing and response mechanisms
- Configuration Management: Unified approach to loading, saving, and validating agent configurations
- State Management: Centralized state tracking and persistence
- Threading Support: Built-in support for asynchronous operations and thread safety
Base Classes and Inheritance Hierarchy
The framework establishes a clear inheritance hierarchy that promotes code reuse and consistency:
classDiagram
class AgentBase {
+string Name
+bool IsEnabled
+DateTime LastUpdated
+void Initialize()
+void Update()
+void Cleanup()
+void LoadConfiguration()
+void SaveConfiguration()
+event EventHandler OnStateChanged
}
class ManagerBase {
+T[] Entries
+Dictionary~string, object~ Properties
+void AddEntry(T entry)
+void RemoveEntry(string id)
+T GetEntry(string id)
+void ProcessEntries()
+void ValidateEntries()
}
class AutolootManager {
+AutolootEntry[] Rules
+void EvaluateLootConditions()
+void ExecuteLootActions()
+void HandleItemDrop()
}
class DressManager {
+DressAgentEntry[] Outfits
+void EvaluateOutfitRules()
+void EquipItems()
+void UnequipItems()
}
class ScavengerManager {
+ScavengerEntry[] ScavengeRules
+void FindScavengeTargets()
+void MoveToTarget()
+void PickUpItems()
}
AgentBase <|-- ManagerBase
ManagerBase <|-- AutolootManager
ManagerBase <|-- DressManager
ManagerBase <|-- ScavengerManager
Diagram sources
Rule Engine Integration
The rule engine serves as the core decision-making component, evaluating conditions and executing appropriate actions. It supports:
- Complex Condition Evaluation: Boolean logic with AND, OR, NOT operators
- Property Matching: Dynamic property comparison using wildcards and regular expressions
- Context-Aware Conditions: Access to game state, player status, and environmental factors
- Priority-Based Execution: Ordered evaluation of multiple rules with conflict resolution
Data Model Architecture
Each agent type defines its own entry models that specify the configuration and behavior parameters:
| Agent Type | Entry Model | Key Properties | Purpose |
|---|---|---|---|
| Autoloot | AutolootEntry | ItemCriteria, Actions, Priority | Define what items to collect and how to handle them |
| Dress | DressAgentEntry | OutfitName, Items, Conditions | Specify equipment combinations and activation rules |
| Scavenger | ScavengerEntry | TargetTypes, PickupRange, Actions | Configure automatic item gathering behavior |
Section sources
Architecture Overview
The agent framework follows a layered architecture that separates concerns and promotes maintainability:
sequenceDiagram
participant Game as "Game Engine"
participant EventSystem as "Event System"
participant AgentManager as "Agent Manager"
participant RuleEngine as "Rule Engine"
participant Agent as "Specific Agent"
participant ActionQueue as "Action Queue"
participant GameClient as "Game Client"
Game->>EventSystem : Game Event
EventSystem->>AgentManager : Dispatch Event
AgentManager->>RuleEngine : Evaluate Conditions
RuleEngine->>Agent : Check Agent Rules
Agent->>Agent : Process Logic
Agent->>ActionQueue : Queue Actions
ActionQueue->>GameClient : Execute Actions
GameClient-->>Game : Send Commands
Note over Agent,ActionQueue : Asynchronous action processing
Note over RuleEngine,Agent : Thread-safe condition evaluation
Diagram sources
Detailed Component Analysis
AutolootManager Analysis
The AutolootManager handles automatic item collection based on configurable rules. It processes incoming item drop events and determines whether items should be picked up based on defined criteria.
Key Features:
- Multi-Criteria Matching: Supports matching by name, hue, weight, value, and custom properties
- Smart Filtering: Advanced filtering with regex support and property-based conditions
- Action Queuing: Intelligent queuing of pickup actions to prevent conflicts
- Priority System: Multiple rules can match an item, with priority determining which action takes precedence
Implementation Pattern:
flowchart TD
Start([Item Drop Event]) --> ParseItem["Parse Item Properties"]
ParseItem --> LoadRules["Load Active Autoloot Rules"]
LoadRules --> EvaluateRules["Evaluate Each Rule"]
EvaluateRules --> MatchFound{"Any Rule Matches?"}
MatchFound --> |No| IgnoreItem["Ignore Item"]
MatchFound --> |Yes| DetermineAction["Determine Best Action"]
DetermineAction --> QueueAction["Queue Pickup Action"]
QueueAction --> End([Process Complete])
IgnoreItem --> End
Diagram sources
Section sources
DressManager Analysis
The DressManager automates equipment changes based on situational awareness and predefined outfit configurations. It monitors game state and automatically equips or unequips items to optimize character performance.
Core Functionality:
- Outfit Management: Create and manage multiple outfit configurations
- Conditional Activation: Activate outfits based on combat mode, location, or other game states
- Inventory Awareness: Understand current inventory and equipped items
- Conflict Resolution: Handle situations where required items are not available
State Machine:
stateDiagram-v2
[*] --> Idle
Idle --> Monitoring : "Start Agent"
Monitoring --> ConditionCheck : "Periodic Check"
ConditionCheck --> NeedsChange{"Outfit Change Needed?"}
NeedsChange --> |No| Monitoring
NeedsChange --> |Yes| PrepareChange["Prepare Item Changes"]
PrepareChange --> HasItems{"All Items Available?"}
HasItems --> |No| LogError["Log Missing Items"]
HasItems --> |Yes| ExecuteChange["Execute Equipment Change"]
ExecuteChange --> VerifyChange["Verify New Outfit"]
VerifyChange --> Monitoring
LogError --> Monitoring
Monitoring --> [*] : "Stop Agent"
Diagram sources
Section sources
ScavengerManager Analysis
The ScavengerManager provides automatic item collection capabilities, allowing characters to gather specific types of items from the ground without manual intervention.
Advanced Features:
- Pathfinding Integration: Intelligent movement to target locations
- Range Management: Respects pickup range limitations and pathfinding obstacles
- Batch Processing: Efficiently handles multiple items in close proximity
- Safety Checks: Avoids dangerous areas and respects game mechanics
Processing Pipeline:
flowchart TD
ScanArea["Scan Area for Items"] --> FilterItems["Filter by Criteria"]
FilterItems --> Prioritize["Prioritize Targets"]
Prioritize --> Pathfind["Calculate Path to Target"]
Pathfind --> CanReach{"Can Reach Target?"}
CanReach --> |No| SkipTarget["Skip and Try Next"]
CanReach --> |Yes| MoveToTarget["Move to Target Location"]
MoveToTarget --> PickUpItem["Pick Up Item"]
PickUpItem --> InventoryCheck{"Inventory Full?"}
InventoryCheck --> |Yes| ReturnHome["Return to Home Location"]
InventoryCheck --> |No| ContinueScavenging["Continue Scavenging"]
SkipTarget --> ContinueScavenging
ReturnHome --> ScanArea
ContinueScavenging --> ScanArea
Diagram sources
Section sources
Dependency Analysis
The agent framework maintains loose coupling between components while ensuring proper data flow and event handling:
graph LR
subgraph "Core Dependencies"
Engine[Engine]
Network[Network Layer]
Objects[Object System]
Filters[Filter System]
end
subgraph "Agent Managers"
AutoLoot[AUTOLootManager]
Dress[DressManager]
Scavenger[ScavengerManager]
end
subgraph "External Systems"
GameAPI[Game API]
Storage[Storage System]
UI[UI System]
end
Engine --> AutoLoot
Engine --> Dress
Engine --> Scavenger
AutoLoot --> Objects
Dress --> Objects
Scavenger --> Objects
AutoLoot --> Filters
Dress --> Filters
Scavenger --> Filters
AutoLoot --> Network
Dress --> Network
Scavenger --> Network
AutoLoot --> Storage
Dress --> Storage
Scavenger --> Storage
AutoLoot --> UI
Dress --> UI
Scavenger --> UI
Diagram sources
Section sources
Performance Considerations
Threading Model
The agent framework implements a multi-threaded architecture designed for optimal performance:
- Main Thread: UI updates and critical game interactions
- Worker Threads: Rule evaluation and complex calculations
- Background Tasks: File I/O and network operations
- Thread-Safe Collections: All shared data structures use concurrent collections
Memory Management
Key memory optimization strategies include:
- Object Pooling: Reuse frequently created objects to reduce GC pressure
- Lazy Loading: Load agent configurations only when needed
- Event Unsubscription: Proper cleanup of event handlers to prevent memory leaks
- Weak References: Use weak references for long-lived observers
Optimization Techniques
- Caching: Cache frequently accessed game data and rule evaluations
- Batch Processing: Group similar operations to minimize overhead
- Early Exit: Short-circuit expensive operations when possible
- Asynchronous Operations: Non-blocking I/O and network calls
Troubleshooting Guide
Common Issues and Solutions
Agent Not Starting:
- Verify agent configuration syntax
- Check for missing dependencies or invalid property values
- Review error logs for initialization failures
Poor Performance:
- Reduce number of active rules per agent
- Optimize condition complexity and avoid expensive operations
- Monitor memory usage and garbage collection frequency
Incorrect Behavior:
- Enable debug logging for detailed operation traces
- Test individual rules in isolation
- Verify game state assumptions in conditions
Debugging Tools
The framework provides comprehensive debugging capabilities:
- Live Rule Evaluation: Real-time testing of condition logic
- Performance Profiling: Identify bottlenecks in rule processing
- State Inspection: Examine agent internal state and variables
- Event Tracing: Track game events and agent responses
Section sources
Conclusion
The ClassicAssist.Avalonia agent framework provides a robust, extensible foundation for creating intelligent automation agents. Its manager-based architecture, combined with a powerful rule engine and comprehensive threading model, enables developers to create sophisticated agents that can handle complex gameplay scenarios efficiently.
The framework's design emphasizes modularity, performance, and ease of extension, making it suitable for both simple automation tasks and complex AI behaviors. By following the established patterns and leveraging the built-in utilities, developers can create reliable agents that enhance the Ultima Online gaming experience.
Appendices
Creating Custom Agents
To implement a custom agent:
- Extend the Base Manager Class: Create a new class inheriting from the appropriate base manager
- Define Entry Models: Create configuration classes for your agent's rules
- Implement Lifecycle Methods: Override initialization, update, and cleanup methods
- Register Event Handlers: Subscribe to relevant game events
- Add Configuration Support: Implement save/load functionality for your rules
- Create UI Components: Build user interfaces for configuring your agent
Best Practices
- Keep Rules Simple: Break complex logic into smaller, testable components
- Handle Errors Gracefully: Always validate inputs and handle exceptions
- Use Appropriate Threading: Keep UI operations on the main thread
- Monitor Performance: Profile regularly and optimize hot paths
- Document Your Rules: Provide clear descriptions for complex conditions