first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,511 @@
|
||||
# Macro System
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.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
|
||||
This document explains the macro system used by ClassicAssist.Avalonia, focusing on how macros are defined, executed, and extended. It covers:
|
||||
- Python scripting integration, including IntelliSense support and debugging considerations
|
||||
- The macro editor interface and command registration system
|
||||
- Parameter handling mechanisms for macro commands
|
||||
- Built-in command categories (action, movement, targeting, spell, agent)
|
||||
- Command API guidance for custom commands with error handling and validation
|
||||
- Practical automation scenarios and advanced scripting techniques
|
||||
- Performance considerations for long-running macros and memory management
|
||||
- Troubleshooting guidance for script debugging and common pitfalls
|
||||
|
||||
## Project Structure
|
||||
The macro system spans shared logic and Avalonia UI layers:
|
||||
- Shared core: macro execution engine, command registry, built-in commands, parameter types, and helpers
|
||||
- Avalonia UI: macro editor tabs, command window, dispatcher/UI invoker integration, and Python completion data
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Core"
|
||||
MM["MacroManager"]
|
||||
MI["MacroInvoker"]
|
||||
ME["MacroEntry"]
|
||||
PT["ParameterType"]
|
||||
SMW["SystemMessageTextWriter"]
|
||||
UOL["UseOnceList"]
|
||||
AC["ActionCommands"]
|
||||
MC["MovementCommands"]
|
||||
TC["TargetCommands"]
|
||||
SC["SpellCommands"]
|
||||
AGC["AgentCommands"]
|
||||
end
|
||||
subgraph "Avalonia UI"
|
||||
MTC["MacrosTabControl"]
|
||||
MCW["MacrosCommandWindow"]
|
||||
AD["AvaloniaDispatcher"]
|
||||
AUI["AvaloniaUIInvoker"]
|
||||
PCD["PythonCompletionData"]
|
||||
end
|
||||
MM --> MI
|
||||
MI --> ME
|
||||
MI --> PT
|
||||
MI --> SMW
|
||||
MI --> UOL
|
||||
MI --> AC
|
||||
MI --> MC
|
||||
MI --> TC
|
||||
MI --> SC
|
||||
MI --> AGC
|
||||
MTC --> MCW
|
||||
MCW --> AD
|
||||
MCW --> AUI
|
||||
PCD --> MTC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
## Core Components
|
||||
- MacroManager: central registry and lifecycle for macros; exposes methods to load, enumerate, and execute macros
|
||||
- MacroInvoker: orchestrates parsing, parameter binding, and dispatching to command implementations
|
||||
- MacroEntry: represents a single macro definition and its metadata
|
||||
- ParameterType: enumerates supported parameter types for command arguments
|
||||
- SystemMessageTextWriter: bridges macro output to in-game/system messages
|
||||
- UseOnceList: helper for one-time use tracking across macro runs
|
||||
- Command Categories:
|
||||
- ActionCommands: general actions (e.g., chat, wait, print)
|
||||
- MovementCommands: pathing and positioning helpers
|
||||
- TargetCommands: target acquisition and selection
|
||||
- SpellCommands: spell casting workflows
|
||||
- AgentCommands: interactions with agents (autoloot, dress, vendor, etc.)
|
||||
|
||||
Key responsibilities:
|
||||
- Registration: commands are discoverable via the command registry
|
||||
- Execution: MacroInvoker parses macro text, resolves parameters, and invokes commands
|
||||
- Output: SystemMessageTextWriter routes messages consistently
|
||||
- UI Integration: Avalonia components provide editing and execution controls
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system follows a layered architecture:
|
||||
- UI Layer (Avalonia): MacrosTabControl and MacrosCommandWindow present macros, accept input, and trigger execution
|
||||
- Orchestration Layer: MacroManager manages macro instances; MacroInvoker executes them
|
||||
- Command Layer: Category-specific command classes implement specific behaviors
|
||||
- Infrastructure: ParameterType defines argument semantics; SystemMessageTextWriter standardizes output; UseOnceList supports stateful behavior
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UI as "MacrosTabControl"
|
||||
participant CmdWin as "MacrosCommandWindow"
|
||||
participant Disp as "AvaloniaDispatcher"
|
||||
participant Inv as "MacroInvoker"
|
||||
participant Cat as "Command Category"
|
||||
participant Out as "SystemMessageTextWriter"
|
||||
User->>UI : Select macro / open command window
|
||||
UI->>CmdWin : Show editor or run dialog
|
||||
User->>CmdWin : Execute macro
|
||||
CmdWin->>Disp : Marshal to UI thread if needed
|
||||
Disp-->>CmdWin : Continue on correct context
|
||||
CmdWin->>Inv : Invoke(macroId, parameters)
|
||||
Inv->>Inv : Parse and bind parameters
|
||||
Inv->>Cat : Dispatch to appropriate command class
|
||||
Cat-->>Inv : Result or exception
|
||||
Inv->>Out : Write status/messages
|
||||
Out-->>User : In-game/system messages
|
||||
Inv-->>CmdWin : Completion status
|
||||
CmdWin-->>User : Update UI feedback
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Macro Execution Engine
|
||||
- MacroManager:
|
||||
- Loads and enumerates macros
|
||||
- Provides entry points to start/stop execution
|
||||
- MacroInvoker:
|
||||
- Parses macro lines into commands
|
||||
- Resolves parameters using ParameterType
|
||||
- Invokes registered command handlers
|
||||
- Writes results via SystemMessageTextWriter
|
||||
- Uses UseOnceList for one-time flags
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MacroManager {
|
||||
+LoadMacros()
|
||||
+GetMacro(id)
|
||||
+ExecuteMacro(id, params)
|
||||
}
|
||||
class MacroInvoker {
|
||||
+Invoke(macroId, parameters)
|
||||
-ParseLine(line)
|
||||
-BindParameters(args)
|
||||
-Dispatch(commandName)
|
||||
-WriteOutput(message)
|
||||
}
|
||||
class MacroEntry {
|
||||
+id
|
||||
+name
|
||||
+scriptText
|
||||
+metadata
|
||||
}
|
||||
class ParameterType {
|
||||
<<enumeration>>
|
||||
}
|
||||
class SystemMessageTextWriter {
|
||||
+Write(text)
|
||||
}
|
||||
class UseOnceList {
|
||||
+Add(item)
|
||||
+Contains(item) bool
|
||||
+Clear()
|
||||
}
|
||||
MacroManager --> MacroInvoker : "uses"
|
||||
MacroInvoker --> MacroEntry : "reads"
|
||||
MacroInvoker --> ParameterType : "binds"
|
||||
MacroInvoker --> SystemMessageTextWriter : "writes"
|
||||
MacroInvoker --> UseOnceList : "tracks"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
|
||||
### Command Registration and Categories
|
||||
- Commands are grouped by category files:
|
||||
- ActionCommands: general-purpose actions
|
||||
- MovementCommands: navigation and positioning
|
||||
- TargetCommands: target selection and acquisition
|
||||
- SpellCommands: spell casting flows
|
||||
- AgentCommands: agent-based automations
|
||||
- Each category implements command handlers that can be invoked by MacroInvoker based on parsed command names
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
MI["MacroInvoker"] --> AC["ActionCommands"]
|
||||
MI --> MC["MovementCommands"]
|
||||
MI --> TC["TargetCommands"]
|
||||
MI --> SC["SpellCommands"]
|
||||
MI --> AGC["AgentCommands"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
### Parameter Handling Mechanisms
|
||||
- ParameterType enumerates supported argument types for commands
|
||||
- MacroInvoker binds arguments from macro text to typed parameters before invoking command handlers
|
||||
- Validation occurs during binding; invalid parameters result in errors reported through SystemMessageTextWriter
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Invoke"]) --> Parse["Parse macro line"]
|
||||
Parse --> Bind["Bind parameters using ParameterType"]
|
||||
Bind --> Valid{"All parameters valid?"}
|
||||
Valid --> |No| Error["Report error via SystemMessageTextWriter"]
|
||||
Valid --> |Yes| Dispatch["Dispatch to command handler"]
|
||||
Dispatch --> Result["Return result/status"]
|
||||
Error --> End(["End"])
|
||||
Result --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
|
||||
### Python Scripting Integration
|
||||
- IntelliSense Support:
|
||||
- PythonCompletionData provides completion entries for the editor
|
||||
- Editor Integration:
|
||||
- MacrosTabControl hosts the macro editor and integrates completion data
|
||||
- Debugging Tools:
|
||||
- MacrosCommandWindow allows running scripts and observing output
|
||||
- Execution Environment:
|
||||
- Dispatcher and UI invoker ensure operations occur on the correct thread context
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Editor as "MacrosTabControl"
|
||||
participant Completion as "PythonCompletionData"
|
||||
participant Win as "MacrosCommandWindow"
|
||||
participant Disp as "AvaloniaDispatcher"
|
||||
participant UIInv as "AvaloniaUIInvoker"
|
||||
Editor->>Completion : Request completions
|
||||
Completion-->>Editor : Provide completion list
|
||||
User->>Win : Run Python script
|
||||
Win->>Disp : Ensure UI thread context
|
||||
Disp-->>Win : Context ready
|
||||
Win->>UIInv : Perform UI updates safely
|
||||
UIInv-->>Win : Updates applied
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
- [MacrosTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/MacrosTabControl.axaml.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
### Command API for Custom Commands
|
||||
Guidance for developing custom macro commands:
|
||||
- Implement command handlers within an appropriate category file
|
||||
- Use ParameterType to define expected argument types
|
||||
- Validate inputs early and report errors via SystemMessageTextWriter
|
||||
- Avoid blocking operations; offload heavy work to background tasks and marshal UI updates using AvaloniaDispatcher/AvaloniaUIInvoker
|
||||
- Keep handlers idempotent where possible; leverage UseOnceList for one-time behaviors
|
||||
|
||||
Best practices:
|
||||
- Clear parameter descriptions and usage hints
|
||||
- Handle exceptions gracefully and log meaningful messages
|
||||
- Prefer small, composable commands over monolithic ones
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
### Practical Automation Scenarios
|
||||
Common patterns:
|
||||
- Action loops: repeat a sequence with conditional checks and delays
|
||||
- Movement sequences: navigate to waypoints and interact with objects
|
||||
- Targeting workflows: acquire targets based on criteria and perform follow-up actions
|
||||
- Spell routines: cast spells with preconditions and post-cast checks
|
||||
- Agent orchestration: coordinate multiple agents (autoloot, vendor, dress) in a pipeline
|
||||
|
||||
Advanced techniques:
|
||||
- Stateful macros using UseOnceList to track progress across runs
|
||||
- Composing smaller commands into higher-level workflows
|
||||
- Using SystemMessageTextWriter for structured logging and diagnostics
|
||||
|
||||
[No sources needed since this section provides conceptual examples without analyzing specific files]
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies among macro components:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
MM["MacroManager"] --> MI["MacroInvoker"]
|
||||
MI --> ME["MacroEntry"]
|
||||
MI --> PT["ParameterType"]
|
||||
MI --> SMW["SystemMessageTextWriter"]
|
||||
MI --> UOL["UseOnceList"]
|
||||
MI --> AC["ActionCommands"]
|
||||
MI --> MC["MovementCommands"]
|
||||
MI --> TC["TargetCommands"]
|
||||
MI --> SC["SpellCommands"]
|
||||
MI --> AGC["AgentCommands"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Long-running macros:
|
||||
- Avoid tight loops without yields; introduce delays or event-driven waits
|
||||
- Offload CPU-intensive work to background threads and marshal UI updates safely
|
||||
- Memory management:
|
||||
- Reuse lists and avoid excessive allocations in hot paths
|
||||
- Clear temporary collections after use; leverage UseOnceList judiciously
|
||||
- I/O and network:
|
||||
- Batch operations when possible; minimize redundant calls
|
||||
- Threading:
|
||||
- Always update UI on the UI thread using AvaloniaDispatcher/AvaloniaUIInvoker
|
||||
- Logging:
|
||||
- Use SystemMessageTextWriter sparingly in tight loops to reduce overhead
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Parameter binding errors:
|
||||
- Verify argument types match ParameterType expectations
|
||||
- Check macro syntax and quoting rules
|
||||
- UI thread violations:
|
||||
- Ensure UI updates are dispatched via AvaloniaDispatcher/AvaloniaUIInvoker
|
||||
- Silent failures:
|
||||
- Inspect SystemMessageTextWriter output for error messages
|
||||
- Add explicit logging around critical sections
|
||||
- Stuck macros:
|
||||
- Review loops and conditionals; add timeouts and break conditions
|
||||
- Python IntelliSense not working:
|
||||
- Confirm PythonCompletionData is loaded and editor bindings are active
|
||||
|
||||
Debugging tips:
|
||||
- Use MacrosCommandWindow to run isolated segments of scripts
|
||||
- Break complex macros into smaller commands for easier testing
|
||||
- Log intermediate states using SystemMessageTextWriter
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Browser/Data/Macros/PythonCompletionData.cs)
|
||||
- [MacrosCommandWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Macros/MacrosCommandWindow.xaml.cs)
|
||||
|
||||
## Conclusion
|
||||
The ClassicAssist.Avalonia macro system provides a robust framework for defining, executing, and extending automation workflows. Its layered architecture separates UI concerns from execution logic, while offering clear extension points for custom commands. By following best practices for parameter handling, threading, and performance, developers can build reliable and efficient macros. Python scripting integration enhances usability with IntelliSense and debugging tools, making it accessible to both novice and advanced users.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
- Command categories reference:
|
||||
- ActionCommands: general actions
|
||||
- MovementCommands: navigation helpers
|
||||
- TargetCommands: target acquisition
|
||||
- SpellCommands: spell casting flows
|
||||
- AgentCommands: agent coordination
|
||||
- UI components:
|
||||
- MacrosTabControl: macro editor host
|
||||
- MacrosCommandWindow: execution and feedback
|
||||
- Infrastructure:
|
||||
- AvaloniaDispatcher: UI thread marshaling
|
||||
- AvaloniaUIInvoker: safe UI updates
|
||||
- PythonCompletionData: editor IntelliSense
|
||||
|
||||
[No sources needed since this section provides references without analyzing specific files]
|
||||
Reference in New Issue
Block a user