first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,482 @@
|
||||
# Action Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.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 action commands available in the ClassicAssist.Avalonia macro system, focusing on user interaction automation such as clicking, right-clicking, dragging and dropping, context menu interactions, and button presses. It provides parameter specifications, return values, usage examples, common pitfalls, multi-step patterns, error handling strategies, execution context, timing considerations, and performance tips. The goal is to help you build robust macros that interact reliably with game entities, items, gumps, and menus.
|
||||
|
||||
## Project Structure
|
||||
The action command functionality is implemented primarily in shared macro command modules and integrates with network packet handling and object models:
|
||||
- Macro command definitions and invoker orchestration
|
||||
- Targeting helpers for selecting entities
|
||||
- Network packets for client actions (context menu, drag/drop, use)
|
||||
- Packet queues and handlers for reliable delivery and response processing
|
||||
- Object model classes for entities, items, mobiles, and gumps
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macros"
|
||||
AC["ActionCommands.cs"]
|
||||
MI["MacroInvoker.cs"]
|
||||
TG["Targeting.cs"]
|
||||
end
|
||||
subgraph "UO Network"
|
||||
Q["ActionPacketQueue.cs"]
|
||||
IPH["IncomingPacketHandlers.cs"]
|
||||
OPH["OutgoingPacketHandlers.cs"]
|
||||
CM["ContextMenuClick.cs"]
|
||||
DI["DragItem.cs"]
|
||||
DO["DropItem.cs"]
|
||||
UO["UseObject.cs"]
|
||||
end
|
||||
subgraph "UO Objects"
|
||||
E["Entity.cs"]
|
||||
I["Item.cs"]
|
||||
M["Mobile.cs"]
|
||||
G["Gump.cs"]
|
||||
end
|
||||
AC --> MI
|
||||
AC --> TG
|
||||
AC --> Q
|
||||
AC --> CM
|
||||
AC --> DI
|
||||
AC --> DO
|
||||
AC --> UO
|
||||
Q --> IPH
|
||||
Q --> OPH
|
||||
AC --> E
|
||||
AC --> I
|
||||
AC --> M
|
||||
AC --> G
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
## Core Components
|
||||
- ActionCommands: Defines macro commands for click, right-click, drag-and-drop, context menu selection, and button presses. It resolves targets, constructs appropriate network packets, and enqueues them for sending.
|
||||
- MacroInvoker: Orchestrates macro execution, parameter parsing, and command dispatch.
|
||||
- Targeting: Provides helpers to resolve target references by ID or other criteria.
|
||||
- Network Packets: ContextMenuClick, DragItem, DropItem, UseObject represent concrete actions sent to the server.
|
||||
- ActionPacketQueue: Queues outgoing action packets and coordinates ordering and timing.
|
||||
- Incoming/Outgoing Handlers: Process responses and ensure state consistency after actions.
|
||||
- Object Models: Entity, Item, Mobile, Gump provide data used to validate and address actions.
|
||||
|
||||
Key responsibilities:
|
||||
- Resolve target objects safely before issuing actions
|
||||
- Build correct packet payloads with IDs, indices, and coordinates
|
||||
- Enqueue actions with proper timing to avoid race conditions
|
||||
- Handle success/failure feedback via packet responses
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system composes high-level commands into low-level network operations:
|
||||
- Macros call ActionCommands methods
|
||||
- ActionCommands validates inputs, resolves targets, and creates packets
|
||||
- ActionPacketQueue orders and sends packets
|
||||
- Handlers process incoming responses and update UI/state
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro Script"
|
||||
participant Invoker as "MacroInvoker"
|
||||
participant Actions as "ActionCommands"
|
||||
participant Queue as "ActionPacketQueue"
|
||||
participant Net as "Network Handlers"
|
||||
participant Game as "Game Server"
|
||||
Macro->>Invoker : Execute macro step
|
||||
Invoker->>Actions : Call action method (e.g., Click, RightClick, DragDrop)
|
||||
Actions->>Actions : Validate parameters and resolve target
|
||||
Actions->>Queue : Enqueue packet (UseObject/ContextMenuClick/DragItem/DropItem)
|
||||
Queue->>Net : Send packet(s)
|
||||
Net-->>Actions : Response events (success/failure)
|
||||
Actions-->>Invoker : Return status/result
|
||||
Invoker-->>Macro : Continue or handle error
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Click Command
|
||||
Purpose: Perform a left-click on a target entity or item.
|
||||
|
||||
Parameters:
|
||||
- Target reference: ID or resolved object (Entity/Item/Mobile)
|
||||
- Optional offset: Relative coordinates if supported by the underlying operation
|
||||
- Optional delay: Milliseconds to wait before executing
|
||||
|
||||
Return value:
|
||||
- Boolean indicating success or failure based on packet send and response
|
||||
|
||||
Usage example:
|
||||
- Click an item in your backpack to inspect it
|
||||
- Left-click a mobile to initiate interaction
|
||||
|
||||
Common pitfalls:
|
||||
- Target not visible or invalid ID leads to failure
|
||||
- Rapid successive clicks may be throttled; add delays between clicks
|
||||
|
||||
Timing considerations:
|
||||
- Insert small delays when chaining multiple clicks to avoid queue saturation
|
||||
|
||||
Integration:
|
||||
- Often followed by context menu selection or property inspection
|
||||
|
||||
Error handling:
|
||||
- Check return value and log failures
|
||||
- Retry with updated target resolution if needed
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
### Right-Click Command
|
||||
Purpose: Open a context menu for a target entity or item.
|
||||
|
||||
Parameters:
|
||||
- Target reference: ID or resolved object
|
||||
- Optional delay: Milliseconds to wait before opening the menu
|
||||
|
||||
Return value:
|
||||
- Boolean indicating success or failure
|
||||
|
||||
Usage example:
|
||||
- Right-click a vendor to open buy/sell options
|
||||
- Right-click a container to view contents
|
||||
|
||||
Common pitfalls:
|
||||
- Some objects do not support context menus; verify capability before invoking
|
||||
- Ensure the target is in range and valid
|
||||
|
||||
Timing considerations:
|
||||
- Allow time for the context menu to appear before selecting an option
|
||||
|
||||
Integration:
|
||||
- Typically followed by a context menu selection command
|
||||
|
||||
Error handling:
|
||||
- If no menu appears, abort subsequent steps and report error
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
### Drag-and-Drop Operations
|
||||
Purpose: Initiate a drag from a source object and drop onto a destination.
|
||||
|
||||
Parameters:
|
||||
- Source reference: ID or resolved object (Item/Mobile)
|
||||
- Destination reference: ID or resolved object (Container/Location)
|
||||
- Optional offsets: Relative coordinates for precise placement
|
||||
- Optional delay: Milliseconds between drag start and drop
|
||||
|
||||
Return value:
|
||||
- Boolean indicating success or failure
|
||||
|
||||
Usage example:
|
||||
- Move an item from backpack to a specific container slot
|
||||
- Transfer gold from one bag to another
|
||||
|
||||
Common pitfalls:
|
||||
- Invalid source or destination types cause immediate failure
|
||||
- Insufficient space at destination results in drop failure
|
||||
- Race conditions if multiple macros manipulate inventory concurrently
|
||||
|
||||
Timing considerations:
|
||||
- Add a short delay after initiating the drag to allow server acknowledgment
|
||||
- Delay before drop to ensure destination is ready
|
||||
|
||||
Integration:
|
||||
- Combine with context menu to open containers prior to drop
|
||||
|
||||
Error handling:
|
||||
- Detect drop failure via packet responses and retry with adjusted parameters
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
### Context Menu Selection
|
||||
Purpose: Select a specific menu entry for a previously opened context menu.
|
||||
|
||||
Parameters:
|
||||
- Menu index or identifier: Numeric index or named entry depending on implementation
|
||||
- Optional delay: Milliseconds to wait before selection
|
||||
|
||||
Return value:
|
||||
- Boolean indicating success or failure
|
||||
|
||||
Usage example:
|
||||
- Choose “Open” from a container’s context menu
|
||||
- Select “Buy” from a vendor’s menu
|
||||
|
||||
Common pitfalls:
|
||||
- Menu entries vary by object type and shard behavior; always verify expected index
|
||||
- Stale menu state if previous context menu did not open correctly
|
||||
|
||||
Timing considerations:
|
||||
- Wait until the context menu is fully rendered before selecting
|
||||
|
||||
Integration:
|
||||
- Follows a right-click command; often precedes further actions like buying or inspecting
|
||||
|
||||
Error handling:
|
||||
- If selection fails, re-open the context menu and retry
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
|
||||
### Button Press (Gump Interaction)
|
||||
Purpose: Interact with gump buttons to confirm dialogs, navigate menus, or trigger actions.
|
||||
|
||||
Parameters:
|
||||
- Gump ID: Identifier of the target gump
|
||||
- Button ID: Specific button within the gump
|
||||
- Optional delay: Milliseconds to wait before pressing
|
||||
|
||||
Return value:
|
||||
- Boolean indicating success or failure
|
||||
|
||||
Usage example:
|
||||
- Confirm a trade window by pressing the accept button
|
||||
- Navigate through wizard-style gumps by pressing next/previous buttons
|
||||
|
||||
Common pitfalls:
|
||||
- Gump may have closed or changed state; verify presence before pressing
|
||||
- Button IDs can differ across shards or versions
|
||||
|
||||
Timing considerations:
|
||||
- Ensure the gump is fully loaded before interacting
|
||||
|
||||
Integration:
|
||||
- Often follows context menu selections or confirmation prompts
|
||||
|
||||
Error handling:
|
||||
- If the gump is not found, abort and report missing dialog
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
|
||||
### Multi-Step Automation Example
|
||||
Scenario: Buy an item from a vendor using a macro sequence.
|
||||
|
||||
Steps:
|
||||
1. Right-click the vendor to open its context menu
|
||||
2. Select the “Buy” menu entry
|
||||
3. Locate the desired item in the vendor list
|
||||
4. Click the buy button or press the corresponding gump button
|
||||
5. Confirm the transaction if prompted
|
||||
6. Verify purchase success and proceed
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start"]) --> RC["Right-click Vendor"]
|
||||
RC --> |Success| BM["Select 'Buy' Entry"]
|
||||
RC --> |Failure| AbortRC["Abort: No Menu"]
|
||||
BM --> |Success| LI["Locate Item"]
|
||||
BM --> |Failure| AbortBM["Abort: Wrong Index"]
|
||||
LI --> |Found| BB["Press Buy Button"]
|
||||
LI --> |Not Found| AbortLI["Abort: Item Missing"]
|
||||
BB --> |Success| Conf["Confirm Transaction"]
|
||||
BB --> |Failure| AbortBB["Abort: Button Error"]
|
||||
Conf --> |Success| Done(["Done"])
|
||||
Conf --> |Failure| AbortConf["Abort: Confirmation Failed"]
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
## Dependency Analysis
|
||||
Action commands depend on several subsystems:
|
||||
- MacroInvoker for command dispatch and parameter handling
|
||||
- Targeting for resolving target references
|
||||
- Network packets for constructing and sending actions
|
||||
- Packet queue for ordering and timing
|
||||
- Handlers for processing responses and updating state
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
MI["MacroInvoker.cs"] --> AC["ActionCommands.cs"]
|
||||
AC --> TG["Targeting.cs"]
|
||||
AC --> CM["ContextMenuClick.cs"]
|
||||
AC --> DI["DragItem.cs"]
|
||||
AC --> DO["DropItem.cs"]
|
||||
AC --> UO["UseObject.cs"]
|
||||
AC --> Q["ActionPacketQueue.cs"]
|
||||
Q --> IPH["IncomingPacketHandlers.cs"]
|
||||
Q --> OPH["OutgoingPacketHandlers.cs"]
|
||||
AC --> E["Entity.cs"]
|
||||
AC --> I["Item.cs"]
|
||||
AC --> M["Mobile.cs"]
|
||||
AC --> G["Gump.cs"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ContextMenuClick.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContextMenuClick.cs)
|
||||
- [DragItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DragItem.cs)
|
||||
- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch actions where possible: Group related clicks or menu selections to reduce overhead
|
||||
- Use minimal delays: Only add necessary pauses to avoid race conditions
|
||||
- Avoid redundant target resolution: Cache resolved IDs when safe to reuse
|
||||
- Monitor packet queue depth: Excessive queuing can cause latency; throttle macro speed
|
||||
- Prefer direct object references: When possible, pass resolved objects instead of repeated lookups
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Target not found: Validate IDs and visibility before action; implement fallback logic
|
||||
- Context menu does not open: Re-attempt right-click; verify object supports context menus
|
||||
- Drag-and-drop fails: Check destination capacity and type compatibility; adjust offsets
|
||||
- Gump button press ignored: Confirm gump exists and button ID matches current state
|
||||
- Timing errors: Increase delays between steps; observe server responses for readiness
|
||||
|
||||
Error handling patterns:
|
||||
- Always check return values of action commands
|
||||
- Log detailed context (target ID, action type, parameters) on failure
|
||||
- Implement retries with backoff for transient failures
|
||||
- Provide clear macro termination points when prerequisites are not met
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
|
||||
## Conclusion
|
||||
Action commands in the ClassicAssist.Avalonia macro system enable powerful automation of clicks, context menu interactions, drag-and-drop, and gump button presses. By understanding parameter specifications, return values, timing, and integration points, you can construct robust macros that handle complex workflows reliably. Apply the recommended error handling and performance practices to minimize failures and optimize execution speed.
|
||||
@@ -0,0 +1,528 @@
|
||||
# Agent Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [MacrosCommandViewModel.cs](file://ClassicAssist/UI/ViewModels/Macros/MacrosCommandViewModel.cs)
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.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 provides detailed documentation for agent control commands within the ClassicAssist.Avalonia macro system. It covers starting, stopping, configuring, and monitoring automation agents including autoloot, dressing, scavenger, and vendor agents. The guide includes parameter specifications for agent configuration, rule modification, and status monitoring. It also provides examples of orchestration patterns, conditional activation, complex workflows, state management, error handling, performance monitoring, and integration strategies between multiple agents.
|
||||
|
||||
## Project Structure
|
||||
The agent command surface is implemented primarily in shared macro command modules and coordinated by UI components that expose agent-specific tabs and controls. Key areas include:
|
||||
- Macro command implementations for agent control
|
||||
- Agent managers for autoloot, dress, scavenger, and vendor operations
|
||||
- UI tab controllers and view models for agent configuration and monitoring
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macro Commands"
|
||||
AC["AgentCommands.cs"]
|
||||
end
|
||||
subgraph "Agent Managers"
|
||||
ALM["AutolootManager.cs"]
|
||||
DM["DressManager.cs"]
|
||||
SM["ScavengerManager.cs"]
|
||||
VBA["VendorBuyAgentEntry.cs"]
|
||||
VSA["VendorSellAgentEntry.cs"]
|
||||
end
|
||||
subgraph "UI Tabs"
|
||||
ATC["AgentsTabControl.xaml.cs"]
|
||||
ALC["AutolootTabControl.xaml.cs"]
|
||||
DTC["DressTabControl.xaml.cs"]
|
||||
STC["ScavengerTabControl.xaml.cs"]
|
||||
VBTC["VendorBuyTabControl.xaml.cs"]
|
||||
VSTC["VendorSellTabControl.xaml.cs"]
|
||||
end
|
||||
subgraph "Macro Command UI"
|
||||
MCV["MacrosCommandViewModel.cs"]
|
||||
end
|
||||
AC --> ALM
|
||||
AC --> DM
|
||||
AC --> SM
|
||||
AC --> VBA
|
||||
AC --> VSA
|
||||
ATC --> ALC
|
||||
ATC --> DTC
|
||||
ATC --> STC
|
||||
ATC --> VBTC
|
||||
ATC --> VSTC
|
||||
MCV --> AC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [MacrosCommandViewModel.cs](file://ClassicAssist/UI/ViewModels/Macros/MacrosCommandViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [MacrosCommandViewModel.cs](file://ClassicAssist/UI/ViewModels/Macros/MacrosCommandViewModel.cs)
|
||||
|
||||
## Core Components
|
||||
- AgentCommands: Implements macro commands to start, stop, configure, and query agent states across autoloot, dressing, scavenger, and vendor subsystems.
|
||||
- AutolootManager: Manages autoloot rules, constraints, and runtime behavior.
|
||||
- DressManager: Controls dressing rules and item equipping logic.
|
||||
- ScavengerManager: Handles scavenger rules and item collection behaviors.
|
||||
- VendorBuyAgentEntry / VendorSellAgentEntry: Define vendor buy/sell agent entries and associated parameters.
|
||||
- UI Tab Controllers: Provide user-facing interfaces for agent configuration and monitoring.
|
||||
|
||||
Key responsibilities:
|
||||
- Expose macro commands for agent lifecycle (start/stop), configuration updates, and status queries.
|
||||
- Coordinate with manager classes to apply changes and reflect current state.
|
||||
- Support rule modifications via structured parameters.
|
||||
- Enable monitoring through status reporting and event-driven updates.
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutlootManager.cs)
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The agent control architecture follows a layered approach:
|
||||
- Macro Command Layer: Parses and executes agent control commands.
|
||||
- Manager Layer: Encapsulates agent-specific logic and state.
|
||||
- UI Layer: Provides configuration and monitoring interfaces.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro Engine"
|
||||
participant Cmd as "AgentCommands"
|
||||
participant ALM as "AutolootManager"
|
||||
participant DM as "DressManager"
|
||||
participant SM as "ScavengerManager"
|
||||
participant VBA as "VendorBuyAgentEntry"
|
||||
participant VSA as "VendorSellAgentEntry"
|
||||
Macro->>Cmd : "agent_start(agent_type, params)"
|
||||
Cmd->>ALM : "StartAutoloot(params)"
|
||||
Cmd->>DM : "StartDressing(params)"
|
||||
Cmd->>SM : "StartScavenger(params)"
|
||||
Cmd->>VBA : "StartVendorBuy(params)"
|
||||
Cmd->>VSA : "StartVendorSell(params)"
|
||||
Macro->>Cmd : "agent_stop(agent_type)"
|
||||
Cmd->>ALM : "StopAutoloot()"
|
||||
Cmd->>DM : "StopDressing()"
|
||||
Cmd->>SM : "StopScavenger()"
|
||||
Cmd->>VBA : "StopVendorBuy()"
|
||||
Cmd->>VSA : "StopVendorSell()"
|
||||
Macro->>Cmd : "agent_status(agent_type)"
|
||||
Cmd-->>Macro : "{state, details}"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### AgentCommands
|
||||
AgentCommands exposes macro-level functions to control agents. Typical capabilities include:
|
||||
- Start/Stop: Lifecycle control for each agent type.
|
||||
- Configure: Apply or update agent settings and rules.
|
||||
- Status: Query current state and details.
|
||||
|
||||
Parameter categories commonly used:
|
||||
- Agent type identifier (e.g., autoloot, dress, scavenger, vendor_buy, vendor_sell).
|
||||
- Rule definitions (conditions, priorities, filters).
|
||||
- Operational flags (enable/disable specific behaviors).
|
||||
- Targeting constraints (entities, items, locations).
|
||||
|
||||
Example usage patterns:
|
||||
- Start an agent with minimal defaults.
|
||||
- Stop an agent gracefully.
|
||||
- Update a rule set and reapply.
|
||||
- Retrieve status for monitoring dashboards.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Macro Call"]) --> Parse["Parse Parameters"]
|
||||
Parse --> Validate{"Valid?"}
|
||||
Validate --> |No| Error["Return Error"]
|
||||
Validate --> |Yes| Dispatch["Dispatch to Manager"]
|
||||
Dispatch --> Apply["Apply Configuration/Action"]
|
||||
Apply --> Report["Report Status"]
|
||||
Report --> End(["Done"])
|
||||
Error --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
### Autoloot Agent
|
||||
Responsibilities:
|
||||
- Manage autoloot rules and constraints.
|
||||
- Evaluate incoming items against configured criteria.
|
||||
- Execute pick-up actions based on priority and conditions.
|
||||
|
||||
Configuration parameters:
|
||||
- Item filters (name, hue, properties).
|
||||
- Constraints (distance, owner, container).
|
||||
- Priority ordering and exclusions.
|
||||
|
||||
Status monitoring:
|
||||
- Active/inactive state.
|
||||
- Matched items count.
|
||||
- Last action timestamp.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AutolootManager {
|
||||
+AddRule(rule)
|
||||
+RemoveRule(id)
|
||||
+UpdateRule(id, rule)
|
||||
+Start()
|
||||
+Stop()
|
||||
+GetStatus()
|
||||
}
|
||||
class AutolootEntry {
|
||||
+id
|
||||
+filters
|
||||
+constraints
|
||||
+priority
|
||||
}
|
||||
class AutolootConstraintEntry {
|
||||
+type
|
||||
+value
|
||||
}
|
||||
AutolootManager --> AutolootEntry : "manages"
|
||||
AutolootEntry --> AutolootConstraintEntry : "uses"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
|
||||
- [AutolootEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootEntry.cs)
|
||||
- [AutolootConstraintEntry.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootConstraintEntry.cs)
|
||||
|
||||
### Dress Agent
|
||||
Responsibilities:
|
||||
- Maintain dressing rules for equipping items.
|
||||
- Handle layer-based equipment logic.
|
||||
- Respect conflicts and compatibility checks.
|
||||
|
||||
Configuration parameters:
|
||||
- Target layers (head, torso, legs, etc.).
|
||||
- Item selection criteria (body, hue, quality).
|
||||
- Conditional triggers (buff presence, health thresholds).
|
||||
|
||||
Status monitoring:
|
||||
- Current equipped items per layer.
|
||||
- Pending changes queue.
|
||||
- Last applied dress action.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DressManager {
|
||||
+AddRule(rule)
|
||||
+RemoveRule(id)
|
||||
+UpdateRule(id, rule)
|
||||
+Start()
|
||||
+Stop()
|
||||
+GetStatus()
|
||||
}
|
||||
class DressAgentEntry {
|
||||
+id
|
||||
+layer
|
||||
+item_criteria
|
||||
+condition
|
||||
}
|
||||
DressManager --> DressAgentEntry : "manages"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
|
||||
- [DressAgentEntry.cs](file://ClassicAssist.Shared/Data/Dress/DressAgentEntry.cs)
|
||||
|
||||
### Scavenger Agent
|
||||
Responsibilities:
|
||||
- Identify and collect specified items from the environment.
|
||||
- Navigate to targets and interact with containers.
|
||||
- Enforce safety constraints (combat, distance).
|
||||
|
||||
Configuration parameters:
|
||||
- Item lists and search scopes.
|
||||
- Container preferences and exclusion rules.
|
||||
- Movement and targeting constraints.
|
||||
|
||||
Status monitoring:
|
||||
- Items found/picked up counts.
|
||||
- Current target and path progress.
|
||||
- Errors encountered during navigation.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ScavengerManager {
|
||||
+AddRule(rule)
|
||||
+RemoveRule(id)
|
||||
+UpdateRule(id, rule)
|
||||
+Start()
|
||||
+Stop()
|
||||
+GetStatus()
|
||||
}
|
||||
class ScavengerEntry {
|
||||
+id
|
||||
+item_filters
|
||||
+container_rules
|
||||
+movement_constraints
|
||||
}
|
||||
ScavengerManager --> ScavengerEntry : "manages"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ScavengerManager.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerManager.cs)
|
||||
- [ScavengerEntry.cs](file://ClassicAssist.Shared/Data/Scavenger/ScavengerEntry.cs)
|
||||
|
||||
### Vendor Agents (Buy/Sell)
|
||||
Responsibilities:
|
||||
- Automate buying and selling transactions with vendors.
|
||||
- Manage shop lists and pricing constraints.
|
||||
- Handle inventory space and gold limits.
|
||||
|
||||
Configuration parameters:
|
||||
- Buy/sell lists with quantities and price caps.
|
||||
- Vendor proximity and interaction rules.
|
||||
- Inventory capacity checks and fallback behaviors.
|
||||
|
||||
Status monitoring:
|
||||
- Transactions completed/failed.
|
||||
- Remaining stock/gold.
|
||||
- Queue depth and processing rate.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VendorBuyAgentEntry {
|
||||
+id
|
||||
+shop_list
|
||||
+price_caps
|
||||
+quantity_limits
|
||||
}
|
||||
class VendorSellAgentEntry {
|
||||
+id
|
||||
+sell_list
|
||||
+min_gold_threshold
|
||||
+inventory_checks
|
||||
}
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
**Section sources**
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
### UI Integration and Monitoring
|
||||
UI tabs provide configuration and real-time monitoring for each agent:
|
||||
- AgentsTabControl: Central hub for agent overview and quick actions.
|
||||
- AutolootTabControl: Rule editor and match statistics.
|
||||
- DressTabControl: Layer-based dress rule management.
|
||||
- ScavengerTabControl: Search scope and navigation controls.
|
||||
- VendorBuyTabControl / VendorSellTabControl: Shop list editors and transaction logs.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant UI as "AgentsTabControl"
|
||||
participant SubTab as "Sub Tab Control"
|
||||
participant Cmd as "AgentCommands"
|
||||
participant Manager as "Agent Manager"
|
||||
User->>UI : "Open Agent Tab"
|
||||
UI->>SubTab : "Load Sub Tab View"
|
||||
User->>SubTab : "Edit Rules/Settings"
|
||||
SubTab->>Cmd : "agent_configure(agent_type, params)"
|
||||
Cmd->>Manager : "Apply Changes"
|
||||
Manager-->>SubTab : "Updated Status"
|
||||
SubTab-->>User : "Reflect Changes"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
Agent commands depend on manager implementations and are surfaced through UI components. The following diagram illustrates key dependencies:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
AC["AgentCommands.cs"] --> ALM["AutolootManager.cs"]
|
||||
AC --> DM["DressManager.cs"]
|
||||
AC --> SM["ScavengerManager.cs"]
|
||||
AC --> VBA["VendorBuyAgentEntry.cs"]
|
||||
AC --> VSA["VendorSellAgentEntry.cs"]
|
||||
ATC["AgentsTabControl.xaml.cs"] --> ALC["AutolootTabControl.xaml.cs"]
|
||||
ATC --> DTC["DressTabControl.xaml.cs"]
|
||||
ATC --> STC["ScavengerTabControl.xaml.cs"]
|
||||
ATC --> VBTC["VendorBuyTabControl.xaml.cs"]
|
||||
ATC --> VSTC["VendorSellTabControl.xaml.cs"]
|
||||
MCV["MacrosCommandViewModel.cs"] --> AC
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [MacrosCommandViewModel.cs](file://ClassicAssist/UI/ViewModels/Macros/MacrosCommandViewModel.cs)
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
- [AgentsTabControl.xaml.cs](file://ClassicAssist/UI/Views/AgentsTabControl.xaml.cs)
|
||||
- [AutolootTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/AutolootTabControl.xaml.cs)
|
||||
- [DressTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/DressTabControl.xaml.cs)
|
||||
- [ScavengerTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/ScavengerTabControl.xaml.cs)
|
||||
- [VendorBuyTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorBuyTabControl.xaml.cs)
|
||||
- [VendorSellTabControl.xaml.cs](file://ClassicAssist/UI/Views/Agents/VendorSellTabControl.xaml.cs)
|
||||
- [MacrosCommandViewModel.cs](file://ClassicAssist/UI/ViewModels/Macros/MacrosCommandViewModel.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Rule evaluation efficiency: Keep filter sets concise; avoid overly broad matches to reduce CPU overhead.
|
||||
- Batch updates: Group multiple rule changes into single configuration calls when possible.
|
||||
- Throttling: Introduce delays between frequent actions (e.g., vendor transactions) to prevent network congestion.
|
||||
- State caching: Cache frequently accessed data (item properties, vendor lists) to minimize repeated lookups.
|
||||
- Logging level: Use appropriate verbosity to balance diagnostics with performance.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Agent fails to start: Verify required parameters and permissions; check manager initialization logs.
|
||||
- Rule not applied: Confirm rule ID exists and syntax is correct; reapply configuration.
|
||||
- No items matched: Review filter criteria and constraints; ensure game state aligns with expectations.
|
||||
- Vendor transaction errors: Check gold availability, inventory space, and vendor proximity.
|
||||
- Status inconsistencies: Refresh agent status; restart agent if necessary.
|
||||
|
||||
Diagnostic steps:
|
||||
- Use agent_status to retrieve detailed state.
|
||||
- Inspect UI tab logs for recent actions and errors.
|
||||
- Temporarily disable other agents to isolate conflicts.
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [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)
|
||||
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
|
||||
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
|
||||
|
||||
## Conclusion
|
||||
Agent control commands in ClassicAssist.Avalonia provide a robust framework for automating gameplay tasks through well-defined macros. By leveraging start/stop operations, configuration updates, and status monitoring, users can orchestrate complex workflows involving autoloot, dressing, scavenger, and vendor agents. Adhering to best practices for rule design, performance tuning, and error handling ensures reliable and efficient automation.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Parameter Specifications Summary
|
||||
- Agent type identifiers: autoloot, dress, scavenger, vendor_buy, vendor_sell.
|
||||
- Common parameters:
|
||||
- enable/disable flags
|
||||
- rule definitions (filters, constraints, priorities)
|
||||
- targeting and movement constraints
|
||||
- operational thresholds (gold, inventory limits)
|
||||
- Status fields:
|
||||
- state (active/inactive/error)
|
||||
- counters (matches, transactions, actions)
|
||||
- timestamps (last action, last update)
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Orchestration Patterns
|
||||
- Sequential execution: Start autoloot, then scavenger after combat ends.
|
||||
- Conditional activation: Enable dressing only when buff thresholds are met.
|
||||
- Parallel coordination: Run vendor buy and sell agents concurrently with conflict resolution.
|
||||
- Fallback strategies: If vendor fails, switch to alternative vendor or pause until conditions improve.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
@@ -0,0 +1,540 @@
|
||||
# Built-in Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [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)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MainCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MainCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [GumpCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/GumpCommands.cs)
|
||||
- [MenuCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MenuCommands.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [ListCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ListCommands.cs)
|
||||
- [AliasCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AliasCommands.cs)
|
||||
- [ConsumeCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ConsumeCommands.cs)
|
||||
- [WandCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/WandCommands.cs)
|
||||
- [AbilitiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AbilitiesCommands.cs)
|
||||
- [SkillCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SkillCommands.cs)
|
||||
- [RegionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/RegionCommands.cs)
|
||||
- [NotorietyCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/NotorietyCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
- [OrganizerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/OrganizerCommands.cs)
|
||||
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
|
||||
- [CommandsDisplayStringSeeAlsoAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayStringSeeAlsoAttribute.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [MovementCommands.cs (Hotkeys)](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
- [UseInHand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseInHand.cs)
|
||||
- [UseLastObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseLastObject.cs)
|
||||
- [EquipLastWeapon.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [StopCurrentMacroCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/StopCurrentMacroCommand.cs)
|
||||
- [StopAllMacrosCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/StopAllMacrosCommand.cs)
|
||||
- [ToggleHotkeys.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleHotkeys.cs)
|
||||
- [WarModeCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/WarModeCommands.cs)
|
||||
- [FriendsCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/FriendsCommands.cs)
|
||||
- [Resync.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Resync.cs)
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.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 provides comprehensive documentation for all built-in macro commands available in ClassicAssist.Avalonia. It covers command categories including action, movement, targeting, spell, agent, object, and utility commands. For each command, it specifies parameters, return values, usage examples, common pitfalls, cross-references, and complex automation scenarios. It also addresses execution context, timing considerations, and error handling patterns.
|
||||
|
||||
## Project Structure
|
||||
The macro command system is implemented primarily under the Shared project’s Data/Macros/Commands directory. Each category of commands is encapsulated in its own file, with a central manager responsible for discovery, registration, and invocation. The macro engine integrates with hotkeys, UI, and game networking layers to execute actions safely within the correct thread and timing context.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macro System"
|
||||
CM["CommandsManager"]
|
||||
MI["MacroInvoker"]
|
||||
ME["MacroEntry"]
|
||||
MM["MacroManager"]
|
||||
PT["ParameterType"]
|
||||
CDA["CommandsDisplayAttribute"]
|
||||
CSAA["CommandsDisplayStringSeeAlsoAttribute"]
|
||||
SMTW["SystemMessageTextWriter"]
|
||||
UOL["UseOnceList"]
|
||||
end
|
||||
subgraph "Command Categories"
|
||||
AC["ActionCommands"]
|
||||
MC["MovementCommands"]
|
||||
TC["TargetCommands"]
|
||||
SC["SpellCommands"]
|
||||
AGC["AgentCommands"]
|
||||
OC["ObjectCommands"]
|
||||
TMC["TimerCommands"]
|
||||
MNC["MainCommands"]
|
||||
PC["PropertiesCommands"]
|
||||
EC["EntityCommands"]
|
||||
MBC["MobileCommands"]
|
||||
GC["GumpCommands"]
|
||||
MEC["MenuCommands"]
|
||||
JC["JournalCommands"]
|
||||
LC["ListCommands"]
|
||||
ALC["AliasCommands"]
|
||||
CC["ConsumeCommands"]
|
||||
WC["WandCommands"]
|
||||
ABC["AbilitiesCommands"]
|
||||
SKC["SkillCommands"]
|
||||
RC["RegionCommands"]
|
||||
NC["NotorietyCommands"]
|
||||
MSGC["MsgCommands"]
|
||||
ORGC["OrganizerCommands"]
|
||||
end
|
||||
CM --> AC
|
||||
CM --> MC
|
||||
CM --> TC
|
||||
CM --> SC
|
||||
CM --> AGC
|
||||
CM --> OC
|
||||
CM --> TMC
|
||||
CM --> MNC
|
||||
CM --> PC
|
||||
CM --> EC
|
||||
CM --> MBC
|
||||
CM --> GC
|
||||
CM --> MEC
|
||||
CM --> JC
|
||||
CM --> LC
|
||||
CM --> ALC
|
||||
CM --> CC
|
||||
CM --> WC
|
||||
CM --> ABC
|
||||
CM --> SKC
|
||||
CM --> RC
|
||||
CM --> NC
|
||||
CM --> MSGC
|
||||
CM --> ORGC
|
||||
MI --> CM
|
||||
ME --> MI
|
||||
MM --> ME
|
||||
MI --> PT
|
||||
MI --> CDA
|
||||
MI --> CSAA
|
||||
MI --> SMTW
|
||||
MI --> UOL
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [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)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MainCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MainCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [GumpCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/GumpCommands.cs)
|
||||
- [MenuCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MenuCommands.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [ListCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ListCommands.cs)
|
||||
- [AliasCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AliasCommands.cs)
|
||||
- [ConsumeCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ConsumeCommands.cs)
|
||||
- [WandCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/WandCommands.cs)
|
||||
- [AbilitiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AbilitiesCommands.cs)
|
||||
- [SkillCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SkillCommands.cs)
|
||||
- [RegionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/RegionCommands.cs)
|
||||
- [NotorietyCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/NotorietyCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
- [OrganizerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/OrganizerCommands.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
|
||||
- [CommandsDisplayStringSeeAlsoAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayStringSeeAlsoAttribute.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
|
||||
**Section sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
|
||||
- [CommandsDisplayStringSeeAlsoAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayStringSeeAlsoAttribute.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [UseOnceList.cs](file://ClassicAssist.Shared/Data/Macros/UseOnceList.cs)
|
||||
|
||||
## Core Components
|
||||
- CommandsManager: Central registry that discovers and exposes macro commands to the macro engine. It handles parameter parsing, validation, and dispatch to specific command implementations.
|
||||
- MacroInvoker: Executes macro entries, manages parameter binding, and coordinates with the macro runtime environment.
|
||||
- Command Attributes: CommandsDisplayAttribute and CommandsDisplayStringSeeAlsoAttribute provide metadata for help and cross-references.
|
||||
- ParameterType: Defines supported parameter types for macro commands.
|
||||
- SystemMessageTextWriter: Provides a safe way to write messages from macros into the game client UI.
|
||||
- UseOnceList: Utility for tracking one-time use items or flags during macro execution.
|
||||
|
||||
These components collectively enable robust macro execution, consistent parameter handling, and helpful diagnostics.
|
||||
|
||||
**Section sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
|
||||
- [CommandsDisplayStringSeeAlsoAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayStringSeeAlsoAttribute.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)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system follows a layered architecture:
|
||||
- Macro Layer: MacroEntry and MacroManager define and manage macro scripts.
|
||||
- Invocation Layer: MacroInvoker parses and executes commands with typed parameters.
|
||||
- Command Registry: CommandsManager registers and routes commands to their implementations.
|
||||
- Game Integration: Commands interact with game objects, packets, and UI through shared services.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant MacroMgr as "MacroManager"
|
||||
participant MacroInv as "MacroInvoker"
|
||||
participant CmdMgr as "CommandsManager"
|
||||
participant Cmd as "Specific Command"
|
||||
participant Engine as "Engine"
|
||||
User->>MacroMgr : Start macro
|
||||
MacroMgr->>MacroInv : Execute entry
|
||||
MacroInv->>CmdMgr : Resolve command by name
|
||||
CmdMgr-->>MacroInv : Command handler
|
||||
MacroInv->>Cmd : Invoke with parsed parameters
|
||||
Cmd->>Engine : Perform game action
|
||||
Engine-->>Cmd : Result/status
|
||||
Cmd-->>MacroInv : Return value
|
||||
MacroInv-->>MacroMgr : Progress/logging
|
||||
MacroMgr-->>User : Completion/error
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Action Commands
|
||||
Action commands perform direct interactions such as clicking, right-clicking, dragging, and dropping items. They are essential for automating inventory management, vendor interactions, and gump navigation.
|
||||
|
||||
- click: Simulates a left-click on an object or UI element. Parameters typically include target ID or screen coordinates, button type, and optional delay. Returns success/failure status.
|
||||
- right-click: Opens context menus or performs secondary actions. Parameters mirror click but specify right-button behavior.
|
||||
- drag-drop: Initiates a drag operation and drops onto a target. Requires source and destination identifiers, plus timing controls.
|
||||
|
||||
Common pitfalls:
|
||||
- Target must be valid and visible; otherwise, the action fails.
|
||||
- Timing delays are crucial to avoid packet throttling or server-side rate limits.
|
||||
- Ensure the player is not in combat when performing certain actions.
|
||||
|
||||
Cross-references:
|
||||
- Object commands for selecting targets before action.
|
||||
- Timer commands for pacing sequences.
|
||||
- Gump commands for navigating UI flows.
|
||||
|
||||
Usage example pattern:
|
||||
- Select item -> click to inspect -> right-click to open menu -> drag to container -> drop.
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
|
||||
### Movement Commands
|
||||
Movement commands control character locomotion, including walking, running, jumping, and pathfinding. They integrate with the game’s movement request pipeline.
|
||||
|
||||
- walk: Moves the character step-by-step toward a destination. Accepts coordinates or relative directions.
|
||||
- run: Similar to walk but uses faster movement mode where allowed.
|
||||
- jump: Triggers a jump action, useful for terrain traversal.
|
||||
|
||||
Timing considerations:
|
||||
- Movement requests are queued and subject to server validation.
|
||||
- Introduce small delays between consecutive moves to prevent stutter or desync.
|
||||
|
||||
Pitfalls:
|
||||
- Obstacles and line-of-sight constraints can block movement.
|
||||
- Running may be restricted in certain regions or states.
|
||||
|
||||
Cross-references:
|
||||
- Region commands to check location constraints.
|
||||
- Agent commands to coordinate movement with other agents.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
|
||||
### Targeting Commands
|
||||
Targeting commands select entities based on criteria such as type, distance, or name. They are foundational for subsequent actions like spells or attacks.
|
||||
|
||||
- target_by_type: Selects the nearest entity matching a body or type filter.
|
||||
- target_by_distance: Chooses an entity within a specified radius.
|
||||
- target_by_name: Targets an entity by exact or partial name.
|
||||
|
||||
Return values:
|
||||
- Success indicates a valid target was set; failure implies no match or invalid parameters.
|
||||
|
||||
Pitfalls:
|
||||
- Filters must be precise to avoid unintended targets.
|
||||
- Distance calculations depend on current map and visibility.
|
||||
|
||||
Cross-references:
|
||||
- Spell commands require a valid target before casting.
|
||||
- Entity and mobile commands rely on current target state.
|
||||
|
||||
**Section sources**
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
|
||||
### Spell Commands
|
||||
Spell commands handle casting, canceling, and queuing spells. They interface with the spell system and target queues.
|
||||
|
||||
- cast: Casts a named or numeric spell at the current target or self. Supports mana checks and cooldowns.
|
||||
- cancel: Interrupts ongoing spellcasting or cancels pending casts.
|
||||
- queue: Adds a spell to the cast queue for sequential execution.
|
||||
|
||||
Execution context:
|
||||
- Casting requires appropriate skill levels and mana.
|
||||
- Some spells require multi-target selection or confirmation prompts.
|
||||
|
||||
Pitfalls:
|
||||
- Insufficient mana or skill will cause failures.
|
||||
- Server-side restrictions may block certain spells in specific areas.
|
||||
|
||||
Cross-references:
|
||||
- Abilities commands for special weapon abilities.
|
||||
- Hotkey interrupt command for emergency cancellation.
|
||||
|
||||
**Section sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
|
||||
### Agent Commands
|
||||
Agent commands control autonomous behaviors such as autoloot, dress, organizer, scavenger, and vendor agents.
|
||||
|
||||
- start: Activates an agent with given configuration.
|
||||
- stop: Halts an agent and clears its queue.
|
||||
- configure: Updates agent settings dynamically.
|
||||
|
||||
Parameters:
|
||||
- Agent type identifier and JSON-like configuration payload.
|
||||
|
||||
Pitfalls:
|
||||
- Agents may conflict if multiple operate on overlapping resources.
|
||||
- Configuration must match expected schema; otherwise, the agent fails to start.
|
||||
|
||||
Cross-references:
|
||||
- Organizer commands for detailed organization rules.
|
||||
- Timer commands to schedule periodic agent runs.
|
||||
|
||||
**Section sources**
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
|
||||
### Object Commands
|
||||
Object commands inspect and modify properties of items and mobiles. They support reading attributes, changing hues, and updating custom properties.
|
||||
|
||||
- inspect: Retrieves detailed information about an object.
|
||||
- modify_properties: Sets property values on an object, respecting server permissions.
|
||||
|
||||
Return values:
|
||||
- Inspection returns structured data; modification returns success/failure.
|
||||
|
||||
Pitfalls:
|
||||
- Property modifications may be restricted by ownership or server policies.
|
||||
- Large batches of updates should be throttled to avoid network congestion.
|
||||
|
||||
Cross-references:
|
||||
- Properties commands for advanced property operations.
|
||||
- List commands to iterate over collections of objects.
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
|
||||
### Utility Commands
|
||||
Utility commands provide timers, conditionals, loops, messaging, and control flow helpers.
|
||||
|
||||
- timer: Creates scheduled tasks with callbacks or delayed executions.
|
||||
- conditional: Evaluates expressions and branches macro flow accordingly.
|
||||
- loop: Repeats blocks of commands with iteration counters and break conditions.
|
||||
|
||||
Timing considerations:
|
||||
- Timers run on the macro scheduler; ensure they do not overload the main loop.
|
||||
- Conditionals should avoid heavy computations to keep macros responsive.
|
||||
|
||||
Pitfalls:
|
||||
- Infinite loops can freeze macro execution; always include exit conditions.
|
||||
- Excessive timers may interfere with other agents or hotkeys.
|
||||
|
||||
Cross-references:
|
||||
- Journal commands for event-driven triggers.
|
||||
- Msg commands for logging and debugging output.
|
||||
|
||||
**Section sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
|
||||
### Additional Command Categories
|
||||
- Main commands: Core utilities for macro lifecycle and global settings.
|
||||
- Properties commands: Advanced property manipulation and filtering.
|
||||
- Entity and Mobile commands: Operations on generic entities and player/mobile characters.
|
||||
- Gump and Menu commands: Interact with in-game UI elements and menus.
|
||||
- Journal commands: Read and parse journal entries for quest tracking.
|
||||
- List commands: Manage lists and collections within macros.
|
||||
- Alias commands: Define reusable command aliases.
|
||||
- Consume commands: Use consumable items intelligently.
|
||||
- Wand commands: Automate wand-based actions.
|
||||
- Abilities commands: Trigger weapon abilities and special moves.
|
||||
- Skill commands: Lock/unlock skills and adjust skill priorities.
|
||||
- Region commands: Query region attributes and boundaries.
|
||||
- Notoriety commands: Filter targets by reputation color.
|
||||
- Msg commands: Send chat messages and logs.
|
||||
- Organizer commands: Configure item organization rules.
|
||||
|
||||
Each category builds upon the core infrastructure and integrates with game systems via shared services.
|
||||
|
||||
**Section sources**
|
||||
- [MainCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MainCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [GumpCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/GumpCommands.cs)
|
||||
- [MenuCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MenuCommands.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [ListCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ListCommands.cs)
|
||||
- [AliasCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AliasCommands.cs)
|
||||
- [ConsumeCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ConsumeCommands.cs)
|
||||
- [WandCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/WandCommands.cs)
|
||||
- [AbilitiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AbilitiesCommands.cs)
|
||||
- [SkillCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SkillCommands.cs)
|
||||
- [RegionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/RegionCommands.cs)
|
||||
- [NotorietyCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/NotorietyCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
- [OrganizerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/OrganizerCommands.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
Macro commands depend on several subsystems:
|
||||
- CommandsManager orchestrates command resolution and dispatch.
|
||||
- MacroInvoker binds parameters and executes commands within the macro runtime.
|
||||
- Engine provides access to game state, networking, and UI integration.
|
||||
- Hotkey commands complement macro commands by providing quick-access actions.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CommandsManager {
|
||||
+Register(command)
|
||||
+Resolve(name)
|
||||
+Invoke(context, params)
|
||||
}
|
||||
class MacroInvoker {
|
||||
+Execute(entry)
|
||||
+BindParameters(args)
|
||||
+HandleErrors()
|
||||
}
|
||||
class Engine {
|
||||
+GetPlayer()
|
||||
+SendPacket(packet)
|
||||
+ShowMessage(text)
|
||||
}
|
||||
class HotkeyCommand {
|
||||
+Execute()
|
||||
}
|
||||
CommandsManager --> MacroInvoker : "uses"
|
||||
MacroInvoker --> Engine : "calls"
|
||||
HotkeyCommand --> Engine : "calls"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
|
||||
|
||||
**Section sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch operations: Group multiple object modifications to reduce network overhead.
|
||||
- Throttle timers: Avoid creating excessive timers; reuse existing ones where possible.
|
||||
- Conditional checks: Keep conditionals lightweight to maintain responsiveness.
|
||||
- Movement pacing: Insert small delays between movement commands to prevent desync.
|
||||
- Spell casting: Respect cooldowns and mana thresholds to minimize retries.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Command not found: Verify command name and spelling; ensure the command is registered in CommandsManager.
|
||||
- Invalid target: Confirm target exists and is visible; use targeting commands to refine selection.
|
||||
- Permission denied: Some object modifications require ownership or server privileges.
|
||||
- Network errors: Check connectivity and server status; retry failed actions with backoff.
|
||||
- Macro hangs: Review loops and timers for infinite iterations; add timeouts and breaks.
|
||||
|
||||
Diagnostic tools:
|
||||
- SystemMessageTextWriter for logging macro progress.
|
||||
- Journal commands to track events and errors.
|
||||
- Msg commands to send debug messages to chat.
|
||||
|
||||
**Section sources**
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
|
||||
## Conclusion
|
||||
The built-in macro command system in ClassicAssist.Avalonia offers a comprehensive toolkit for automating gameplay tasks. By leveraging action, movement, targeting, spell, agent, object, and utility commands, users can create sophisticated automation workflows. Proper attention to execution context, timing, and error handling ensures reliable and efficient macro performance.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Complex Automation Scenarios
|
||||
- Vendor restock automation:
|
||||
- Use list commands to gather items.
|
||||
- Employ consume commands to prepare consumables.
|
||||
- Navigate vendor gumps using gump commands.
|
||||
- Apply timer commands to pace purchases.
|
||||
- Monitor journal for transaction confirmations.
|
||||
|
||||
- Combat rotation:
|
||||
- Target enemies using targeting commands with notoriety filters.
|
||||
- Cast spells via spell commands with mana checks.
|
||||
- Trigger abilities using abilities commands.
|
||||
- Move strategically with movement commands.
|
||||
- Cancel spells with interrupt command if needed.
|
||||
|
||||
- Inventory organization:
|
||||
- Inspect items with object commands.
|
||||
- Modify properties to sort by criteria.
|
||||
- Use organizer commands to automate placement.
|
||||
- Loop through containers with list commands.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
@@ -0,0 +1,459 @@
|
||||
# Movement Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.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 movement commands in the ClassicAssist.Avalonia macro system. It covers walking, running, jumping, mounting/dismounting, and pathfinding commands. It includes parameter specifications (coordinates, directions, speed settings, navigation targets), practical examples for automation, timing considerations, collision detection behavior, performance optimization for large-scale movement, error handling for failed movements, and integration with targeting systems.
|
||||
|
||||
## Project Structure
|
||||
Movement-related functionality spans shared macro/hotkey command implementations, UO data and math utilities, and packet-level pathfinding support:
|
||||
- Macro and hotkey command definitions expose user-facing commands to macros and hotkeys.
|
||||
- UO data types provide direction, map, and math helpers used by movement logic.
|
||||
- Pathfinding packets integrate with the game client/server protocol for advanced routing.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macro System"
|
||||
MC["Macros/MovementCommands.cs"]
|
||||
HC["Hotkeys/MovementCommands.cs"]
|
||||
end
|
||||
subgraph "UO Data & Math"
|
||||
DIR["Direction.cs"]
|
||||
MAP["Map.cs"]
|
||||
MATH["UOMath.cs"]
|
||||
end
|
||||
subgraph "Networking"
|
||||
PF["Packets/Pathfind.cs"]
|
||||
end
|
||||
subgraph "Entities"
|
||||
MOB["Mobile.cs"]
|
||||
PMOB["PlayerMobile.cs"]
|
||||
end
|
||||
subgraph "Targeting"
|
||||
TM["TargetManager.cs"]
|
||||
end
|
||||
MC --> DIR
|
||||
MC --> MAP
|
||||
MC --> MATH
|
||||
MC --> PF
|
||||
MC --> MOB
|
||||
MC --> PMOB
|
||||
HC --> MC
|
||||
HC --> TM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
## Core Components
|
||||
- Macro movement commands: Provide high-level movement primitives usable from macros (walk/run/jump/mount/dismount/pathfind).
|
||||
- Hotkey movement commands: Bind movement actions to hotkeys and optionally integrate with targeting.
|
||||
- Direction and map utilities: Represent cardinal directions and coordinate spaces.
|
||||
- Pathfinding packet support: Encodes path requests for server-side or client-side routing.
|
||||
- Entity models: Player/mobile state and properties influence movement behavior (e.g., mounted status).
|
||||
- Targeting integration: Allows moving toward a target or using current target as a destination.
|
||||
|
||||
Key responsibilities:
|
||||
- Validate parameters (coordinates, directions, speed).
|
||||
- Convert logical inputs into network packets or engine calls.
|
||||
- Handle timing and retries for robust movement.
|
||||
- Report errors and success states back to macros/hotkeys.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro/hotkey layer translates user intent into movement actions. For simple steps, it sends direct movement packets; for complex routes, it uses pathfinding. Mounting toggles are handled via dedicated commands. Targeting integration allows dynamic destinations.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro"
|
||||
participant MC as "Macros/MovementCommands.cs"
|
||||
participant DIR as "Direction.cs"
|
||||
participant MAP as "Map.cs"
|
||||
participant PF as "Packets/Pathfind.cs"
|
||||
participant MOB as "PlayerMobile.cs"
|
||||
participant TM as "TargetManager.cs"
|
||||
Macro->>MC : "MoveTo(x,y,map)"
|
||||
MC->>MAP : "Validate coordinates"
|
||||
MC->>DIR : "Compute direction(s)"
|
||||
alt "Simple step"
|
||||
MC-->>MOB : "Send movement request"
|
||||
else "Complex route"
|
||||
MC->>PF : "Request path"
|
||||
PF-->>MC : "Path points"
|
||||
loop "Follow path"
|
||||
MC->>MOB : "Step along path"
|
||||
end
|
||||
end
|
||||
Note over MC,TM : "Optional : use current target as destination"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Walking and Running
|
||||
Purpose:
|
||||
- Move the character one or more steps in a given direction or toward a target.
|
||||
- Support both walking and running modes where applicable.
|
||||
|
||||
Parameters:
|
||||
- Direction: cardinal or ordinal direction values.
|
||||
- Distance: number of steps (optional; defaults may apply).
|
||||
- Mode: walk vs run toggle if supported by the command variant.
|
||||
|
||||
Behavior:
|
||||
- Validates current position and direction.
|
||||
- Sends movement packets to the server.
|
||||
- May respect game constraints (combat, stunned, etc.).
|
||||
|
||||
Timing:
|
||||
- Introduce small delays between steps when issuing multiple moves to avoid input flooding.
|
||||
|
||||
Error handling:
|
||||
- Detect invalid directions or blocked tiles and report failure.
|
||||
|
||||
Practical example:
|
||||
- Walk 5 steps north, then run 3 steps east.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
### Jumping
|
||||
Purpose:
|
||||
- Execute a jump action, typically to clear obstacles or reach elevated areas.
|
||||
|
||||
Parameters:
|
||||
- Optional target location or relative offset.
|
||||
- Timing delay before/after jump.
|
||||
|
||||
Behavior:
|
||||
- Issues jump request packet.
|
||||
- May require line-of-sight or valid landing tile.
|
||||
|
||||
Error handling:
|
||||
- Fails if jump is invalid (blocked, out of bounds).
|
||||
|
||||
Practical example:
|
||||
- Jump forward once to clear a wall segment.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
### Mounting and Dismounting
|
||||
Purpose:
|
||||
- Toggle mount state to enable faster travel or specific interactions.
|
||||
|
||||
Parameters:
|
||||
- None (toggle behavior) or explicit mount selection if supported.
|
||||
|
||||
Behavior:
|
||||
- Uses dedicated mount toggle command.
|
||||
- Integrates with player state to ensure valid transitions.
|
||||
|
||||
Error handling:
|
||||
- Reports failure if no mount available or conditions not met.
|
||||
|
||||
Practical example:
|
||||
- Mount before long-distance travel; dismount near destination.
|
||||
|
||||
**Section sources**
|
||||
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
### Pathfinding and Navigation
|
||||
Purpose:
|
||||
- Compute and follow a multi-step route to a target coordinate or entity.
|
||||
|
||||
Parameters:
|
||||
- Destination coordinates (x, y, map).
|
||||
- Optional target reference (current target or named entity).
|
||||
- Speed setting (walk/run preference).
|
||||
- Obstacle avoidance flags (if exposed).
|
||||
|
||||
Behavior:
|
||||
- Requests path via pathfinding packet.
|
||||
- Iteratively steps along the returned path.
|
||||
- Replans if blocked or invalidated.
|
||||
|
||||
Collision detection:
|
||||
- Relies on server/client validation; macro layer should detect failures and retry or abort.
|
||||
|
||||
Timing:
|
||||
- Pace steps to match game tick rates; add jitter to reduce synchronization issues.
|
||||
|
||||
Error handling:
|
||||
- On path failure, fallback to direct movement or notify macro.
|
||||
|
||||
Practical example:
|
||||
- Navigate to a waypoint while avoiding obstacles; switch to running after clearing dense areas.
|
||||
|
||||
**Section sources**
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [UOMath.cs](file://ClassicAssist.Shared/UO/UOMath.cs)
|
||||
|
||||
### Integration with Targeting Systems
|
||||
Purpose:
|
||||
- Allow movement commands to use the current target as a destination or to move adjacent to a target.
|
||||
|
||||
Parameters:
|
||||
- Target selection mode (current target, nearest, by name).
|
||||
- Offset distance from target.
|
||||
|
||||
Behavior:
|
||||
- Resolves target coordinates via targeting manager.
|
||||
- Converts target-based requests into coordinate-based movement.
|
||||
|
||||
Error handling:
|
||||
- If target is invalid or lost, abort or prompt for new target.
|
||||
|
||||
Practical example:
|
||||
- Move within range of current enemy without engaging.
|
||||
|
||||
**Section sources**
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
|
||||
### Class Relationships
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MovementCommands {
|
||||
+MoveTo(x, y, map)
|
||||
+Walk(direction, steps)
|
||||
+Run(direction, steps)
|
||||
+Jump(offset)
|
||||
+Pathfind(destination)
|
||||
+Mount()
|
||||
+Dismount()
|
||||
}
|
||||
class Direction {
|
||||
+values
|
||||
+toVector()
|
||||
}
|
||||
class Map {
|
||||
+isValid(x,y)
|
||||
+getTile(x,y)
|
||||
}
|
||||
class PathfindPacket {
|
||||
+requestPath(start,end)
|
||||
+parseResponse()
|
||||
}
|
||||
class PlayerMobile {
|
||||
+position
|
||||
+mounted
|
||||
+sendMovement()
|
||||
}
|
||||
class TargetManager {
|
||||
+getCurrentTarget()
|
||||
+resolveCoordinates(target)
|
||||
}
|
||||
MovementCommands --> Direction : "uses"
|
||||
MovementCommands --> Map : "validates"
|
||||
MovementCommands --> PathfindPacket : "requests"
|
||||
MovementCommands --> PlayerMobile : "controls"
|
||||
MovementCommands --> TargetManager : "resolves targets"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
### Sequence: Pathfinding Follow
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro"
|
||||
participant MC as "Macros/MovementCommands.cs"
|
||||
participant PF as "Packets/Pathfind.cs"
|
||||
participant MOB as "PlayerMobile.cs"
|
||||
Macro->>MC : "Pathfind(destX, destY, map)"
|
||||
MC->>PF : "Request path"
|
||||
PF-->>MC : "Path points"
|
||||
loop "For each point"
|
||||
MC->>MOB : "Step to next point"
|
||||
MOB-->>MC : "Status (success/failure)"
|
||||
alt "Failure"
|
||||
MC->>PF : "Replan path"
|
||||
end
|
||||
end
|
||||
MC-->>Macro : "Complete or error"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
### Flowchart: Step Execution
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start Step"]) --> Validate["Validate Coordinates/Direction"]
|
||||
Validate --> Valid{"Valid?"}
|
||||
Valid --> |No| Error["Return Error"]
|
||||
Valid --> |Yes| CheckState["Check Player State<br/>Mounted? Combat?"]
|
||||
CheckState --> CanMove{"Can Move?"}
|
||||
CanMove --> |No| Error
|
||||
CanMove --> |Yes| SendMove["Send Movement Packet"]
|
||||
SendMove --> WaitTick["Wait Game Tick"]
|
||||
WaitTick --> Success{"Success?"}
|
||||
Success --> |No| Retry["Retry or Abort"]
|
||||
Success --> |Yes| Done(["Done"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- Macro movement commands depend on:
|
||||
- Direction and Map utilities for spatial reasoning.
|
||||
- Pathfinding packet interface for complex routing.
|
||||
- PlayerMobile for sending movement and reading state.
|
||||
- TargetManager for resolving dynamic destinations.
|
||||
- Hotkey movement commands wrap macro commands and may add UI/targeting shortcuts.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
HC["Hotkeys/MovementCommands.cs"] --> MC["Macros/MovementCommands.cs"]
|
||||
MC --> DIR["Direction.cs"]
|
||||
MC --> MAP["Map.cs"]
|
||||
MC --> PF["Packets/Pathfind.cs"]
|
||||
MC --> MOB["PlayerMobile.cs"]
|
||||
MC --> TM["TargetManager.cs"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch movement: Group multiple steps to reduce overhead; interleave waits to respect server ticks.
|
||||
- Avoid redundant replanning: Cache paths when possible; only replan on failure or significant deviation.
|
||||
- Use running selectively: Running may be faster but can increase collision checks; prefer walking in tight spaces.
|
||||
- Minimize target resolution: Resolve target coordinates once per routine rather than repeatedly.
|
||||
- Throttle input: Add small random jitter to step timings to prevent lockstep behavior.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Invalid coordinates: Ensure x/y/map are within valid ranges; validate before sending.
|
||||
- Blocked path: If pathfinding fails, fall back to direct movement or adjust destination slightly.
|
||||
- Mounted state conflicts: Dismount before entering interiors or narrow corridors if required.
|
||||
- Target loss: Re-resolve target coordinates if the target disappears mid-route.
|
||||
- Timing errors: Increase wait times between steps; check for combat or stun states that block movement.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
## Conclusion
|
||||
Movement commands in ClassicAssist.Avalonia provide a robust foundation for automated locomotion. By combining simple step controls with pathfinding, mounting toggles, and targeting integration, macros can implement sophisticated navigation patterns. Proper parameter validation, timing control, and error handling ensure reliable operation across diverse scenarios.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Parameter Reference Summary
|
||||
- Coordinates: x, y, map identifiers validated against map boundaries.
|
||||
- Directions: Cardinal/ordinal direction values converted to movement vectors.
|
||||
- Speed settings: Walk vs run preferences applied per step or route segment.
|
||||
- Navigation targets: Current target or resolved entities used as destinations.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
|
||||
- [Map.cs](file://ClassicAssist.Shared/UO/Data/Map.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
### Practical Automation Patterns
|
||||
- Route planning: Define waypoints; use pathfinding between segments; switch to running on open terrain.
|
||||
- Obstacle avoidance: Detect failures and reroute; prefer walking in cluttered areas.
|
||||
- Large-scale movement: Combine mount toggling with batched pathfinding; cache paths; stagger execution.
|
||||
|
||||
**Section sources**
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
|
||||
- [ToggleMounted.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ToggleMounted.cs)
|
||||
@@ -0,0 +1,619 @@
|
||||
# Object Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [UseInHand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseInHand.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
- [EquipLastWeapon.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ObjectInspector.cs](file://ClassicAssist/Data/Hotkeys/Commands/ObjectInspector.cs)
|
||||
- [ObjectInspectorWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml.cs)
|
||||
- [ObjectInspectorViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/ObjectInspectorViewModel.cs)
|
||||
- [ObjectInspectorData.cs](file://ClassicAssist.Shared/UI/Models/ObjectInspectorData.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 provides comprehensive documentation for object manipulation commands in the ClassicAssist macro system, focusing on inspecting objects, reading and modifying properties, inventory management, and equipment handling. It explains parameter specifications for object identification, property access, and value manipulation; demonstrates automated workflows such as inventory organization, equipment switching, and item analysis; and addresses lifecycle management, memory considerations, performance optimization for bulk operations, error handling for invalid objects, and data validation patterns.
|
||||
|
||||
## Project Structure
|
||||
The object command surface is implemented across shared macro command modules and UO networking packets. The Avalonia UI exposes an Object Inspector that leverages the same underlying inspection capabilities.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macro Commands"
|
||||
OC["ObjectCommands.cs"]
|
||||
PC["PropertiesCommands.cs"]
|
||||
EC["EntityCommands.cs"]
|
||||
MC["MobileCommands.cs"]
|
||||
AC["ActionCommands.cs"]
|
||||
TC["TargetCommands.cs"]
|
||||
end
|
||||
subgraph "UO Objects"
|
||||
E["Entity.cs"]
|
||||
I["Item.cs"]
|
||||
M["Mobile.cs"]
|
||||
P["Property.cs"]
|
||||
end
|
||||
subgraph "Networking Packets"
|
||||
QP["QueryProperties.cs"]
|
||||
BQP["BatchQueryProperties.cs"]
|
||||
LR["LookRequest.cs"]
|
||||
UO["UseObject.cs"]
|
||||
ER["EquipRequest.cs"]
|
||||
DR["DisarmRequest.cs"]
|
||||
CCP["ContainerContentsPacket.cs"]
|
||||
CCU["ContainerContentUpdate.cs"]
|
||||
RO["RemoveObject.cs"]
|
||||
end
|
||||
subgraph "UI Inspector"
|
||||
OI["ObjectInspector.cs"]
|
||||
OIW["ObjectInspectorWindow.axaml.cs"]
|
||||
OIVM["ObjectInspectorViewModel.cs"]
|
||||
OID["ObjectInspectorData.cs"]
|
||||
end
|
||||
OC --> E
|
||||
OC --> I
|
||||
OC --> M
|
||||
PC --> P
|
||||
EC --> E
|
||||
MC --> M
|
||||
AC --> UO
|
||||
AC --> ER
|
||||
AC --> DR
|
||||
TC --> UO
|
||||
OI --> OC
|
||||
OIW --> OIVM
|
||||
OIVM --> OC
|
||||
OIVM --> PC
|
||||
OIVM --> OID
|
||||
OC --> QP
|
||||
OC --> BQP
|
||||
OC --> LR
|
||||
PC --> QP
|
||||
PC --> BQP
|
||||
AC --> CCP
|
||||
AC --> CCU
|
||||
AC --> RO
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
- [ObjectInspector.cs](file://ClassicAssist/Data/Hotkeys/Commands/ObjectInspector.cs)
|
||||
- [ObjectInspectorWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml.cs)
|
||||
- [ObjectInspectorViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/ObjectInspectorViewModel.cs)
|
||||
- [ObjectInspectorData.cs](file://ClassicAssist.Shared/UI/Models/ObjectInspectorData.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [ObjectInspector.cs](file://ClassicAssist/Data/Hotkeys/Commands/ObjectInspector.cs)
|
||||
- [ObjectInspectorWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/ObjectInspectorWindow.axaml.cs)
|
||||
- [ObjectInspectorViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/ObjectInspectorViewModel.cs)
|
||||
- [ObjectInspectorData.cs](file://ClassicAssist.Shared/UI/Models/ObjectInspectorData.cs)
|
||||
|
||||
## Core Components
|
||||
- Object inspection: Resolve entities by ID or filter, retrieve basic metadata (name, serial, location), and request detailed property sets via look or property queries.
|
||||
- Property access: Read named properties with type-aware values; batch-read multiple properties efficiently; write supported properties where allowed.
|
||||
- Inventory management: Enumerate containers, read contents, move items between containers, drop held items, and react to container updates.
|
||||
- Equipment handling: Equip/disarm items, use items in hand, and manage last-used weapon state.
|
||||
|
||||
Key implementation anchors:
|
||||
- Object resolution and high-level operations are exposed through macro commands.
|
||||
- Networking layer uses specific packets for look, query/batch-query properties, equip/disarm, use, and container content synchronization.
|
||||
- UI inspector integrates with the same APIs to present live object details.
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system invokes command handlers that operate on entity models and send network requests. Responses update local caches and collections, which are then surfaced to macros and UI components.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro Script"
|
||||
participant Invoker as "MacroInvoker.cs"
|
||||
participant Cmd as "ObjectCommands.cs"
|
||||
participant Net as "Networking Packets"
|
||||
participant Model as "Entity/Item/Mobile"
|
||||
participant UI as "ObjectInspectorViewModel.cs"
|
||||
Macro->>Invoker : Execute command with parameters
|
||||
Invoker->>Cmd : Resolve target(s) and validate inputs
|
||||
Cmd->>Net : Send LookRequest / QueryProperties / BatchQueryProperties
|
||||
Net-->>Model : Update cached properties and metadata
|
||||
Cmd-->>Macro : Return result or status
|
||||
UI->>Cmd : Request object details for display
|
||||
Cmd-->>UI : Provide inspected data
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [ObjectInspectorViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/ObjectInspectorViewModel.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Object Inspection and Identification
|
||||
- Purpose: Identify and inspect entities by serial or filters; fetch names, locations, and other attributes.
|
||||
- Parameters:
|
||||
- Object identifier: serial number or filter criteria (e.g., name pattern, body type).
|
||||
- Depth: whether to include full property set or just basic metadata.
|
||||
- Behavior:
|
||||
- Resolves a single target or collection based on provided criteria.
|
||||
- Sends look request if deeper info is required.
|
||||
- Returns structured object information suitable for scripting or UI.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Inspect Entry"]) --> Parse["Parse Identifier and Options"]
|
||||
Parse --> Valid{"Valid Target?"}
|
||||
Valid --> |No| Error["Return Error: Invalid Object"]
|
||||
Valid --> |Yes| HasProps{"Has Cached Properties?"}
|
||||
HasProps --> |Yes| UseCache["Use Cached Data"]
|
||||
HasProps --> |No| SendLook["Send LookRequest"]
|
||||
SendLook --> Update["Update Cache"]
|
||||
UseCache --> Return["Return Inspected Data"]
|
||||
Update --> Return
|
||||
Error --> End(["Exit"])
|
||||
Return --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
### Property Reading and Writing
|
||||
- Purpose: Access named properties with typed values; support batch reads for efficiency; write when permitted.
|
||||
- Parameters:
|
||||
- Target object identifier.
|
||||
- Property name(s).
|
||||
- For writes: new value and expected type.
|
||||
- Behavior:
|
||||
- Reads from cache if available; otherwise issues QueryProperties or BatchQueryProperties.
|
||||
- Validates property existence and type before returning or writing.
|
||||
- Writes trigger server-side updates only for writable properties.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro Script"
|
||||
participant Props as "PropertiesCommands.cs"
|
||||
participant Net as "Query/Batch Query"
|
||||
participant Model as "Property.cs"
|
||||
Macro->>Props : ReadProperty(target, name)
|
||||
Props->>Model : Check cache for property
|
||||
alt Not cached
|
||||
Props->>Net : Send QueryProperties or BatchQueryProperties
|
||||
Net-->>Model : Populate property list
|
||||
end
|
||||
Props-->>Macro : Typed property value
|
||||
Macro->>Props : WriteProperty(target, name, value)
|
||||
Props->>Model : Validate writability and type
|
||||
Props->>Net : Send update packet (if applicable)
|
||||
Props-->>Macro : Success/Failure
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
**Section sources**
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
### Inventory Management
|
||||
- Purpose: Enumerate containers, read contents, move items, drop held items, and respond to container updates.
|
||||
- Key operations:
|
||||
- List container contents using cached data or refresh via container packets.
|
||||
- Move items between containers (server-driven actions).
|
||||
- Drop held item to ground or target location.
|
||||
- Parameters:
|
||||
- Container identifier (serial).
|
||||
- Source/target item identifiers.
|
||||
- Optional quantity or destination coordinates.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
StartInv(["Inventory Operation"]) --> Identify["Identify Container and Items"]
|
||||
Identify --> Refresh{"Need Refresh?"}
|
||||
Refresh --> |Yes| WaitCC["Wait for ContainerContentsPacket"]
|
||||
Refresh --> |No| Proceed["Proceed with Cached Data"]
|
||||
WaitCC --> Proceed
|
||||
Proceed --> Action{"Operation Type"}
|
||||
Action --> |Move| SendMove["Send Move/Drop Packet"]
|
||||
Action --> |Drop Held| DropHeld["DropHoldingObject"]
|
||||
Action --> |List| ListItems["Enumerate Items"]
|
||||
SendMove --> Update["Handle ContainerContentUpdate"]
|
||||
DropHeld --> Update
|
||||
ListItems --> Done(["Done"])
|
||||
Update --> Done
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
|
||||
### Equipment Handling
|
||||
- Purpose: Equip/disarm items, use items in hand, and manage last-used weapon state.
|
||||
- Operations:
|
||||
- Equip item to appropriate slot.
|
||||
- Disarm current equipped item.
|
||||
- Use item currently held in hand.
|
||||
- Equip last used weapon shortcut.
|
||||
- Parameters:
|
||||
- Item serial for equip/disarm/use.
|
||||
- Slot selection when relevant.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "Macro Script"
|
||||
participant Act as "ActionCommands.cs"
|
||||
participant HK as "Hotkey Commands"
|
||||
participant Net as "Equip/Disarm/Use Packets"
|
||||
Macro->>Act : Equip(itemSerial)
|
||||
Act->>Net : Send EquipRequest
|
||||
Net-->>Macro : Confirmation
|
||||
Macro->>Act : Disarm(slot)
|
||||
Act->>Net : Send DisarmRequest
|
||||
Net-->>Macro : Confirmation
|
||||
Macro->>HK : UseInHand()
|
||||
HK->>Net : Send UseObject
|
||||
Net-->>Macro : Confirmation
|
||||
Macro->>HK : EquipLastWeapon()
|
||||
HK->>Net : Send EquipRequest(lastWeapon)
|
||||
Net-->>Macro : Confirmation
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [UseInHand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseInHand.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
- [EquipLastWeapon.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [UseInHand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseInHand.cs)
|
||||
- [DropHoldingObject.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs)
|
||||
- [EquipLastWeapon.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
|
||||
### Automated Workflows
|
||||
|
||||
#### Inventory Organization Workflow
|
||||
- Steps:
|
||||
- Scan backpack contents.
|
||||
- Filter items by criteria (type, hue, quality).
|
||||
- Move matching items to designated containers.
|
||||
- Confirm moves via container updates.
|
||||
- Validation:
|
||||
- Ensure target container exists and has capacity.
|
||||
- Handle partial moves and errors gracefully.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Start Organize"] --> B["Open Backpack"]
|
||||
B --> C["Read Contents"]
|
||||
C --> D{"Match Criteria?"}
|
||||
D --> |Yes| E["Select Destination Container"]
|
||||
D --> |No| F["Skip Item"]
|
||||
E --> G["Move Item"]
|
||||
G --> H["Verify Update"]
|
||||
F --> I["Next Item"]
|
||||
H --> I
|
||||
I --> J{"More Items?"}
|
||||
J --> |Yes| C
|
||||
J --> |No| K["Finish"]
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
#### Equipment Switching Workflow
|
||||
- Steps:
|
||||
- Identify desired weapon/item.
|
||||
- Equip it to the correct slot.
|
||||
- Optionally disarm previous item.
|
||||
- Use item in hand if needed.
|
||||
- Validation:
|
||||
- Verify item is wearable/equippable.
|
||||
- Handle conflicts (slot occupied).
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as "Script"
|
||||
participant AC as "ActionCommands.cs"
|
||||
participant HK as "EquipLastWeapon.cs"
|
||||
participant NET as "Equip/Disarm/Use"
|
||||
S->>AC : Find item by filter
|
||||
AC-->>S : Item serial
|
||||
S->>AC : Equip(serial)
|
||||
AC->>NET : EquipRequest
|
||||
NET-->>S : Success
|
||||
S->>AC : Disarm(currentSlot)
|
||||
AC->>NET : DisarmRequest
|
||||
NET-->>S : Success
|
||||
S->>HK : UseInHand()
|
||||
HK->>NET : UseObject
|
||||
NET-->>S : Success
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [EquipLastWeapon.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
|
||||
#### Item Analysis Workflow
|
||||
- Steps:
|
||||
- Select item for inspection.
|
||||
- Request look and/or property query.
|
||||
- Aggregate key attributes (name, stats, custom properties).
|
||||
- Output summary for decision-making.
|
||||
- Validation:
|
||||
- Ensure object exists and is visible.
|
||||
- Handle missing properties gracefully.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
X["Analyze Item"] --> Y["Resolve Serial"]
|
||||
Y --> Z["Send LookRequest"]
|
||||
Z --> AA["Send QueryProperties"]
|
||||
AA --> AB["Aggregate Results"]
|
||||
AB --> AC["Display Summary"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
Command implementations depend on core entity models and networking packets. UI components rely on the same command surface to provide interactive inspection.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Entity {
|
||||
+int Serial
|
||||
+string Name
|
||||
+Location Position
|
||||
}
|
||||
class Item {
|
||||
+int Hue
|
||||
+int Amount
|
||||
+bool Equipped
|
||||
}
|
||||
class Mobile {
|
||||
+int Body
|
||||
+int Gold
|
||||
}
|
||||
class Property {
|
||||
+string Name
|
||||
+object Value
|
||||
}
|
||||
class ObjectCommands {
|
||||
+Inspect(target)
|
||||
+GetProperties(target, names)
|
||||
}
|
||||
class PropertiesCommands {
|
||||
+ReadProperty(target, name)
|
||||
+WriteProperty(target, name, value)
|
||||
}
|
||||
class ActionCommands {
|
||||
+Equip(serial)
|
||||
+Disarm(slot)
|
||||
+UseInHand()
|
||||
}
|
||||
class QueryProperties
|
||||
class BatchQueryProperties
|
||||
class LookRequest
|
||||
class EquipRequest
|
||||
class DisarmRequest
|
||||
class UseObject
|
||||
class ContainerContentsPacket
|
||||
class ContainerContentUpdate
|
||||
class RemoveObject
|
||||
ObjectCommands --> Entity : "uses"
|
||||
ObjectCommands --> Item : "uses"
|
||||
ObjectCommands --> Mobile : "uses"
|
||||
PropertiesCommands --> Property : "reads/writes"
|
||||
ObjectCommands --> QueryProperties : "requests"
|
||||
ObjectCommands --> BatchQueryProperties : "batch requests"
|
||||
ObjectCommands --> LookRequest : "look"
|
||||
ActionCommands --> EquipRequest : "equips"
|
||||
ActionCommands --> DisarmRequest : "disarms"
|
||||
ActionCommands --> UseObject : "uses"
|
||||
ActionCommands --> ContainerContentsPacket : "list contents"
|
||||
ActionCommands --> ContainerContentUpdate : "updates"
|
||||
ActionCommands --> RemoveObject : "removals"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [QueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/QueryProperties.cs)
|
||||
- [BatchQueryProperties.cs](file://ClassicAssist.Shared/UO/Network/Packets/BatchQueryProperties.cs)
|
||||
- [LookRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/LookRequest.cs)
|
||||
- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
|
||||
- [DisarmRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/DisarmRequest.cs)
|
||||
- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
|
||||
- [ContainerContentsPacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentsPacket.cs)
|
||||
- [ContainerContentUpdate.cs](file://ClassicAssist.Shared/UO/Network/Packets/ContainerContentUpdate.cs)
|
||||
- [RemoveObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/RemoveObject.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Prefer batch property queries over individual queries to reduce network overhead.
|
||||
- Cache frequently accessed properties and invalidate on relevant updates (container changes, look responses).
|
||||
- Avoid polling loops; rely on event-driven updates from container content packets and removal events.
|
||||
- Limit deep inspections to necessary objects; defer expensive look requests until required.
|
||||
- For bulk operations, group actions and process results asynchronously to prevent blocking the macro thread.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Invalid object identifier: Validate serials and ensure the object exists before operations.
|
||||
- Missing properties: Trigger a look or property query to refresh cache; handle absent properties gracefully.
|
||||
- Permission errors: Some properties are read-only; check writability before attempting writes.
|
||||
- Network timeouts: Implement retries with backoff for look/query requests.
|
||||
- Container desync: Listen for container content updates and remove events to keep local state consistent.
|
||||
|
||||
Error handling patterns:
|
||||
- Always validate input parameters (serials, property names, types).
|
||||
- Return meaningful statuses to macros and log actionable messages.
|
||||
- Use try/catch around network calls and propagate user-friendly errors.
|
||||
|
||||
**Section sources**
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
|
||||
## Conclusion
|
||||
The object command surface in ClassicAssist provides robust capabilities for inspecting objects, managing properties, organizing inventory, and handling equipment. By leveraging batch queries, caching strategies, and event-driven updates, macros can perform efficient and reliable automation. Proper validation and error handling ensure resilience against invalid inputs and transient network conditions.
|
||||
|
||||
## Appendices
|
||||
|
||||
### Parameter Specifications Summary
|
||||
- Object identification:
|
||||
- Serial: integer identifier for precise targeting.
|
||||
- Filters: name patterns, body types, and other attributes for selection.
|
||||
- Property access:
|
||||
- Property name: string key.
|
||||
- Value type: strongly-typed representation returned by the engine.
|
||||
- Writability: determined per property; only writable properties accept updates.
|
||||
- Inventory operations:
|
||||
- Container serial: target container.
|
||||
- Item serials: source and destination items.
|
||||
- Quantities: optional counts for partial moves.
|
||||
- Equipment operations:
|
||||
- Item serial: target item.
|
||||
- Slot: optional slot specification for disarming/equipping.
|
||||
|
||||
**Section sources**
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
@@ -0,0 +1,543 @@
|
||||
# Spell Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.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)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
This document explains spell casting commands within the ClassicAssist.Avalonia macro system. It covers how to cast spells, cancel casts, queue targets, manage mana and cooldowns, and integrate with targeting systems for precise application. It also provides examples for combat rotations, healing automation, buff management, and complex sequences, along with guidance on interruptions, error recovery, and performance optimization for rapid casting.
|
||||
|
||||
## Project Structure
|
||||
The spell command functionality spans several modules:
|
||||
- Macro commands that expose user-facing actions (cast, cancel, last spell, clear queue).
|
||||
- Targeting subsystem for selecting entities and queuing targets.
|
||||
- Spell data and manager for lookup, validation, and metadata.
|
||||
- Network layer for sending cast packets and handling responses.
|
||||
- Macro engine integration for execution context and timing.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Macros"
|
||||
MC["MacroInvoker"]
|
||||
MM["MacroManager"]
|
||||
SCmd["SpellCommands"]
|
||||
ICmd["InterruptSpellCommand"]
|
||||
CLS["CastLastSpell"]
|
||||
COQ["ClearObjectQueue"]
|
||||
end
|
||||
subgraph "Targeting"
|
||||
TM["TargetManager"]
|
||||
TQ["TargetQueue"]
|
||||
TgCmd["Targeting"]
|
||||
end
|
||||
subgraph "Spells"
|
||||
SM["SpellManager"]
|
||||
SD["SpellData"]
|
||||
end
|
||||
subgraph "Network"
|
||||
APQ["ActionPacketQueue"]
|
||||
CS["CastSpell Packet"]
|
||||
CTC["CancelTargetCursor Packet"]
|
||||
IPH["IncomingPacketHandlers"]
|
||||
OPH["OutgoingPacketHandlers"]
|
||||
end
|
||||
subgraph "Game Objects"
|
||||
PM["PlayerMobile"]
|
||||
MColl["MobileCollection"]
|
||||
EColl["EntityCollection"]
|
||||
end
|
||||
SCmd --> SM
|
||||
SCmd --> TM
|
||||
SCmd --> APQ
|
||||
ICmd --> TM
|
||||
CLS --> SM
|
||||
CLS --> TM
|
||||
COQ --> TQ
|
||||
TgCmd --> TM
|
||||
TM --> TQ
|
||||
SM --> SD
|
||||
APQ --> CS
|
||||
APQ --> CTC
|
||||
IPH --> TM
|
||||
OPH --> APQ
|
||||
SCmd --> PM
|
||||
SCmd --> MColl
|
||||
SCmd --> EColl
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
**Section sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Core Components
|
||||
- SpellCommands: Exposes macro commands to cast spells by name or ID, select targets, control positioning, and manage timing. Integrates with SpellManager for validation and TargetManager for selection.
|
||||
- InterruptSpellCommand: Cancels an ongoing cast or target cursor via network packet.
|
||||
- CastLastSpell: Re-casts the most recently used spell using stored context.
|
||||
- ClearObjectQueue: Clears pending target queue entries to reset state.
|
||||
- Targeting: Provides helper hotkey commands for entity selection and targeting workflows.
|
||||
- SpellManager/SpellData: Central registry of spells, their properties, costs, and constraints.
|
||||
- TargetManager/TargetQueue: Manages current target and queued targets for multi-target spells.
|
||||
- ActionPacketQueue: Serializes outgoing actions (casts, cancels) to ensure proper ordering and rate limiting.
|
||||
- Incoming/Outgoing Packet Handlers: Bridge between game events and macro logic (e.g., update player status, handle cast confirmations).
|
||||
- PlayerMobile/MobileCollection/EntityCollection: Provide runtime access to player state and world entities for targeting and conditions.
|
||||
|
||||
**Section sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system composes high-level commands into low-level network actions through a layered architecture:
|
||||
- Command Layer: Macro commands parse parameters and validate inputs.
|
||||
- Domain Layer: Spell and targeting managers enforce rules and maintain state.
|
||||
- Network Layer: ActionPacketQueue serializes packets; handlers react to server responses.
|
||||
- Game State Layer: Entities and collections provide real-time information for decisions.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "MacroInvoker"
|
||||
participant Cmd as "SpellCommands"
|
||||
participant SMan as "SpellManager"
|
||||
participant TMan as "TargetManager"
|
||||
participant Aq as "ActionPacketQueue"
|
||||
participant Net as "Network Packets"
|
||||
participant Server as "Game Server"
|
||||
Macro->>Cmd : "spell_cast(spell_name, target, position, delay)"
|
||||
Cmd->>SMan : "resolve_spell(spell_name)"
|
||||
SMan-->>Cmd : "SpellData"
|
||||
Cmd->>TMan : "select_target(target_spec)"
|
||||
TMan-->>Cmd : "target_id or null"
|
||||
Cmd->>Aq : "enqueue(CastSpell)"
|
||||
Aq->>Net : "send(CastSpell)"
|
||||
Net->>Server : "CastSpell packet"
|
||||
Server-->>Net : "Cast result/status"
|
||||
Net-->>Aq : "acknowledge"
|
||||
Aq-->>Cmd : "success/failure"
|
||||
Cmd-->>Macro : "result"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Spell Casting Command
|
||||
- Purpose: Cast a named spell with optional target, positioning, and timing controls.
|
||||
- Key responsibilities:
|
||||
- Resolve spell by name or ID via SpellManager.
|
||||
- Validate prerequisites (mana, cooldown, range).
|
||||
- Select target using TargetManager helpers.
|
||||
- Enqueue CastSpell packet via ActionPacketQueue.
|
||||
- Handle success/failure and return results to macros.
|
||||
- Parameters typically include:
|
||||
- Spell identifier (name or ID).
|
||||
- Target specification (entity reference, name filter, or auto-select).
|
||||
- Positional offset or relative coordinates for ground-targeted spells.
|
||||
- Delay or wait options to pace casting.
|
||||
- Error handling:
|
||||
- Invalid spell name/ID.
|
||||
- Insufficient mana or out-of-range.
|
||||
- Cooldown not expired.
|
||||
- Target not found or invalid.
|
||||
- Network send failure or server rejection.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["spell_cast entry"]) --> Resolve["Resolve spell by name/ID"]
|
||||
Resolve --> Valid{"Spell valid?"}
|
||||
Valid --> |No| ErrInvalid["Return error: invalid spell"]
|
||||
Valid --> |Yes| CheckMana["Check mana cost and availability"]
|
||||
CheckMana --> ManaOK{"Enough mana?"}
|
||||
ManaOK --> |No| ErrMana["Return error: insufficient mana"]
|
||||
ManaOK --> |Yes| CheckCD["Check spell cooldown"]
|
||||
CheckCD --> CDOK{"Cooldown ready?"}
|
||||
CDOK --> |No| ErrCD["Return error: spell on cooldown"]
|
||||
CDOK --> |Yes| SelectTarget["Select target or position"]
|
||||
SelectTarget --> TargetOK{"Target resolved?"}
|
||||
TargetOK --> |No| ErrTarget["Return error: target not found"]
|
||||
TargetOK --> |Yes| Enqueue["Enqueue CastSpell packet"]
|
||||
Enqueue --> Send["Send via ActionPacketQueue"]
|
||||
Send --> Result{"Server accepted?"}
|
||||
Result --> |No| ErrServer["Return error: server rejected"]
|
||||
Result --> |Yes| Done(["Success"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
|
||||
**Section sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
|
||||
### Cancellation and Interruption
|
||||
- InterruptSpellCommand: Sends CancelTargetCursor to abort a pending target cursor or cast initiation.
|
||||
- Use cases:
|
||||
- Stop a misfired cast.
|
||||
- Cancel targeting when switching priorities.
|
||||
- Recover from stuck states where the client expects a target input.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "MacroInvoker"
|
||||
participant Int as "InterruptSpellCommand"
|
||||
participant TMan as "TargetManager"
|
||||
participant Aq as "ActionPacketQueue"
|
||||
participant Net as "Network Packets"
|
||||
participant Server as "Game Server"
|
||||
Macro->>Int : "interrupt_spell()"
|
||||
Int->>TMan : "check active target/cursor"
|
||||
Int->>Aq : "enqueue(CancelTargetCursor)"
|
||||
Aq->>Net : "send(CancelTargetCursor)"
|
||||
Net->>Server : "CancelTargetCursor packet"
|
||||
Server-->>Net : "acknowledge"
|
||||
Net-->>Aq : "success"
|
||||
Aq-->>Int : "done"
|
||||
Int-->>Macro : "interrupt complete"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
|
||||
|
||||
**Section sources**
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
|
||||
|
||||
### Last Spell Recast
|
||||
- CastLastSpell: Reuses the most recent spell context (ID, target, position) to recast quickly.
|
||||
- Benefits:
|
||||
- Simplifies repetitive casting patterns.
|
||||
- Reduces parsing overhead in tight loops.
|
||||
- Typical usage:
|
||||
- In combat rotations after successful hits.
|
||||
- For quick follow-up casts when conditions are met.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Macro as "MacroInvoker"
|
||||
participant CLS as "CastLastSpell"
|
||||
participant SMan as "SpellManager"
|
||||
participant TMan as "TargetManager"
|
||||
participant Aq as "ActionPacketQueue"
|
||||
participant Net as "Network Packets"
|
||||
Macro->>CLS : "cast_last_spell()"
|
||||
CLS->>SMan : "lookup last spell data"
|
||||
CLS->>TMan : "restore last target if needed"
|
||||
CLS->>Aq : "enqueue(CastSpell with last context)"
|
||||
Aq->>Net : "send(CastSpell)"
|
||||
Net-->>Aq : "acknowledge"
|
||||
Aq-->>CLS : "success/failure"
|
||||
CLS-->>Macro : "result"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
|
||||
**Section sources**
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
|
||||
### Queue Management
|
||||
- ClearObjectQueue: Resets pending target queue entries to avoid stale targets.
|
||||
- TargetQueue: Maintains ordered list of targets for multi-target spells or batch operations.
|
||||
- Integration:
|
||||
- Before casting area effects, clear queue to ensure fresh selection.
|
||||
- After successful casts, optionally clear queue to prevent accidental reapplication.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["clear_object_queue"]) --> Check["Check if queue has items"]
|
||||
Check --> HasItems{"Has items?"}
|
||||
HasItems --> |No| EndEmpty(["Nothing to clear"])
|
||||
HasItems --> |Yes| Reset["Reset TargetQueue state"]
|
||||
Reset --> Notify["Notify TargetManager of cleared state"]
|
||||
Notify --> EndDone(["Queue cleared"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
|
||||
### Targeting Helpers
|
||||
- Targeting: Provides commands to select entities by criteria (friend/enemy), refine selection, and prepare for targeted spells.
|
||||
- Use cases:
|
||||
- Pre-select a specific mobile before casting.
|
||||
- Switch targets dynamically based on health thresholds.
|
||||
- Combine with positioning offsets for ground-targeted spells.
|
||||
|
||||
**Section sources**
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
Key relationships:
|
||||
- SpellCommands depends on SpellManager for spell resolution and validation, TargetManager for selection, and ActionPacketQueue for reliable network dispatch.
|
||||
- InterruptSpellCommand relies on TargetManager to determine whether a cursor is active and sends CancelTargetCursor via ActionPacketQueue.
|
||||
- CastLastSpell uses SpellManager and TargetManager to reconstruct prior cast context.
|
||||
- ClearObjectQueue interacts with TargetQueue and TargetManager to reset state.
|
||||
- Incoming/Outgoing Packet Handlers bridge server events and macro logic, updating PlayerMobile and related collections.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SpellCommands {
|
||||
+cast(spellName, targetSpec, position, delay)
|
||||
+validatePrerequisites()
|
||||
+enqueueCast()
|
||||
}
|
||||
class InterruptSpellCommand {
|
||||
+interrupt()
|
||||
}
|
||||
class CastLastSpell {
|
||||
+recast()
|
||||
}
|
||||
class ClearObjectQueue {
|
||||
+clear()
|
||||
}
|
||||
class Targeting {
|
||||
+selectByCriteria()
|
||||
+refineSelection()
|
||||
}
|
||||
class SpellManager {
|
||||
+resolve(nameOrId)
|
||||
+getCostAndCooldown()
|
||||
}
|
||||
class TargetManager {
|
||||
+setTarget()
|
||||
+getActiveTarget()
|
||||
+clear()
|
||||
}
|
||||
class TargetQueue {
|
||||
+push()
|
||||
+pop()
|
||||
+clear()
|
||||
}
|
||||
class ActionPacketQueue {
|
||||
+enqueue(packet)
|
||||
+flush()
|
||||
}
|
||||
class IncomingPacketHandlers
|
||||
class OutgoingPacketHandlers
|
||||
class PlayerMobile
|
||||
class MobileCollection
|
||||
class EntityCollection
|
||||
SpellCommands --> SpellManager : "resolves spell"
|
||||
SpellCommands --> TargetManager : "selects target"
|
||||
SpellCommands --> ActionPacketQueue : "enqueues cast"
|
||||
InterruptSpellCommand --> TargetManager : "checks cursor"
|
||||
InterruptSpellCommand --> ActionPacketQueue : "cancels"
|
||||
CastLastSpell --> SpellManager : "last spell data"
|
||||
CastLastSpell --> TargetManager : "restore target"
|
||||
ClearObjectQueue --> TargetQueue : "clears queue"
|
||||
ClearObjectQueue --> TargetManager : "notifies"
|
||||
Targeting --> TargetManager : "updates target"
|
||||
IncomingPacketHandlers --> PlayerMobile : "updates state"
|
||||
OutgoingPacketHandlers --> ActionPacketQueue : "dispatches"
|
||||
SpellCommands --> PlayerMobile : "reads stats"
|
||||
SpellCommands --> MobileCollection : "finds entities"
|
||||
SpellCommands --> EntityCollection : "filters objects"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
**Section sources**
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
|
||||
- [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Batch casting:
|
||||
- Use ActionPacketQueue to serialize casts and avoid flooding the network.
|
||||
- Group multiple casts with minimal delays to maximize throughput while respecting server-side limits.
|
||||
- Rapid spell casting:
|
||||
- Prefer CastLastSpell for repeated casts to reduce parameter parsing overhead.
|
||||
- Cache frequently used spell IDs instead of resolving by name repeatedly.
|
||||
- Target selection efficiency:
|
||||
- Pre-select targets using Targeting helpers to minimize lookups during critical moments.
|
||||
- Clear queues before area-effect casts to prevent stale selections.
|
||||
- Mana and cooldown checks:
|
||||
- Perform prerequisite checks early to avoid unnecessary network calls.
|
||||
- Use SpellManager’s cached data for cost and cooldown values.
|
||||
- Timing controls:
|
||||
- Insert small delays between casts to accommodate server processing and animation locks.
|
||||
- Avoid excessive waits that degrade responsiveness.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Spell fails due to insufficient mana:
|
||||
- Verify PlayerMobile’s mana pool and spell cost via SpellManager.
|
||||
- Add mana checks before casting and fallback to non-mana actions.
|
||||
- Spell on cooldown:
|
||||
- Check cooldown status via SpellManager and schedule retries after expiration.
|
||||
- Target not found:
|
||||
- Use Targeting helpers to refine selection criteria.
|
||||
- Ensure MobileCollection and EntityCollection filters match expected entities.
|
||||
- Stuck target cursor:
|
||||
- Invoke InterruptSpellCommand to cancel pending cursors.
|
||||
- Confirm CancelTargetCursor was sent and acknowledged.
|
||||
- Network errors:
|
||||
- Monitor OutgoingPacketHandlers for send failures.
|
||||
- Retry failed casts with backoff and error logging.
|
||||
- Recovery strategies:
|
||||
- Implement retry loops with exponential backoff for transient failures.
|
||||
- Log detailed context (spell ID, target, position, delay) for diagnostics.
|
||||
|
||||
**Section sources**
|
||||
- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
|
||||
## Conclusion
|
||||
The spell command system integrates macro-level actions with robust domain logic and reliable networking. By leveraging SpellManager, TargetManager, and ActionPacketQueue, macros can perform precise, efficient, and resilient spell casting. Proper use of cancellation, queue management, and timing controls enables advanced automation for combat, healing, and buffs, while troubleshooting practices ensure stability under dynamic conditions.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Example Patterns
|
||||
- Combat rotation:
|
||||
- Loop: check enemy presence, cast primary spell, recast last spell if available, interrupt if interrupted, clear queue, delay, repeat.
|
||||
- Healing automation:
|
||||
- Monitor ally health via MobileCollection, cast heal when below threshold, prioritize self-heal if necessary, cancel conflicting casts.
|
||||
- Buff management:
|
||||
- Apply buffs to allies with missing effects, refresh before expiration, avoid redundant casts, manage mana budget.
|
||||
- Complex sequences:
|
||||
- Chain multiple spells with positional offsets, stagger timings, and conditional branching based on server responses.
|
||||
|
||||
[No sources needed since this section provides conceptual examples]
|
||||
@@ -0,0 +1,481 @@
|
||||
# Targeting Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.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 how targeting commands work within the ClassicAssist.Avalonia macro system. It covers selection by type, distance, name, color, and entity properties; advanced scenarios such as conditional targeting, priority-based selection, and dynamic target switching; and operational concerns like validation, timeouts, fallback strategies, performance with large collections, and memory management. The goal is to help you build robust combat automation, resource gathering, and social interaction macros that are efficient and resilient.
|
||||
|
||||
## Project Structure
|
||||
The targeting subsystem spans shared data structures, hotkey command implementations, and macro command handlers:
|
||||
- Hotkey commands for acquiring targets (enemy/friend)
|
||||
- Macro-level targeting commands
|
||||
- Core targeting manager and queue
|
||||
- Entity collections and base types used for filtering and selection
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Hotkey Commands"
|
||||
TAE["TargetAcquisitionEnemy.cs"]
|
||||
TAF["TargetAcquisitionFriend.cs"]
|
||||
TGT["Targeting.cs"]
|
||||
end
|
||||
subgraph "Macro Commands"
|
||||
MC["TargetCommands.cs"]
|
||||
end
|
||||
subgraph "Targeting Core"
|
||||
TM["TargetManager.cs"]
|
||||
TQ["TargetQueue.cs"]
|
||||
TE["Enums.cs"]
|
||||
TBD["TargetBodyData.cs"]
|
||||
end
|
||||
subgraph "Entities"
|
||||
EC["EntityCollection.cs"]
|
||||
MCOL["MobileCollection.cs"]
|
||||
MOB["Mobile.cs"]
|
||||
ENT["Entity.cs"]
|
||||
end
|
||||
TAE --> TM
|
||||
TAF --> TM
|
||||
TGT --> TM
|
||||
MC --> TM
|
||||
TM --> TQ
|
||||
TM --> EC
|
||||
TM --> MCOL
|
||||
MCOL --> MOB
|
||||
MOB --> ENT
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
## Core Components
|
||||
- Targeting hotkey commands: Provide quick acquisition of enemies or friends via hotkeys. They typically query nearby mobiles and issue a targeted action.
|
||||
- Macro targeting commands: Expose higher-level commands usable from scripts/macros to select targets based on criteria and perform actions.
|
||||
- TargetManager: Central coordination for selecting, validating, queuing, and issuing targets.
|
||||
- TargetQueue: Manages ordered sequences of targets for batched or sequential operations.
|
||||
- Enums and body data: Define selectable categories, notoriety rules, and body-type mappings used during selection.
|
||||
- Entity collections: Provide filtered views over entities/mobs for efficient querying.
|
||||
|
||||
Key responsibilities:
|
||||
- Filtering by type, distance, name, color, and properties
|
||||
- Priority and conditional selection
|
||||
- Validation and timeout handling
|
||||
- Queueing and execution of targeting actions
|
||||
|
||||
**Section sources**
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The targeting architecture separates user-facing commands (hotkeys and macros) from core selection logic and execution. Selection uses entity collections and filters; execution uses the target manager and queue.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User/Macro"
|
||||
participant HK as "Hotkey Command"
|
||||
participant MC as "Macro Command"
|
||||
participant TM as "TargetManager"
|
||||
participant COL as "Entity/Mobile Collection"
|
||||
participant Q as "TargetQueue"
|
||||
participant Game as "Game Client"
|
||||
User->>HK : Trigger hotkey
|
||||
HK->>TM : Acquire target (criteria)
|
||||
TM->>COL : Filter by type/distance/name/color/properties
|
||||
COL-->>TM : Candidate set
|
||||
TM->>TM : Apply priority/conditions
|
||||
TM->>Q : Enqueue selected target(s)
|
||||
Q->>Game : Issue target action(s)
|
||||
Game-->>TM : Acknowledge/Status
|
||||
TM-->>HK : Result
|
||||
User->>MC : Call macro targeting command
|
||||
MC->>TM : Select target(s) with advanced criteria
|
||||
TM->>COL : Filter + sort + validate
|
||||
TM->>Q : Enqueue or execute immediately
|
||||
Q->>Game : Send target packets
|
||||
Game-->>TM : Responses
|
||||
TM-->>MC : Outcome and metadata
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Hotkey Target Acquisition (Enemy/Friend)
|
||||
These commands provide fast, context-aware targeting for common gameplay loops. They typically:
|
||||
- Determine player position and range
|
||||
- Query nearby mobiles
|
||||
- Filter by notoriety or friend lists
|
||||
- Issue a targeted attack or assist action
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Hotkey Trigger"]) --> GetPlayer["Get Player Position"]
|
||||
GetPlayer --> QueryNearby["Query Nearby Mobiles"]
|
||||
QueryNearby --> FilterNotoriety{"Filter by Notoriety/Friends?"}
|
||||
FilterNotoriety --> |Yes| ApplyRules["Apply Rules"]
|
||||
FilterNotoriety --> |No| SkipRules["Skip Rules"]
|
||||
ApplyRules --> BestCandidate["Select Best Candidate"]
|
||||
SkipRules --> BestCandidate
|
||||
BestCandidate --> IssueAction["Issue Target Action"]
|
||||
IssueAction --> End(["Done"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
|
||||
### Macro Targeting Commands
|
||||
Macro commands expose richer selection capabilities suitable for automation:
|
||||
- Type-based selection (e.g., specific bodies or categories)
|
||||
- Distance-based selection (nearest, farthest, within radius)
|
||||
- Name-based selection (exact/partial match)
|
||||
- Color/hue-based selection
|
||||
- Property-based selection (flags, stats, custom properties)
|
||||
- Conditional targeting (if/else branches based on environment/state)
|
||||
- Priority-based selection (rank candidates by multiple criteria)
|
||||
- Dynamic target switching (rotate among valid targets)
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TargetManager {
|
||||
+SelectByType(criteria)
|
||||
+SelectByDistance(radius, order)
|
||||
+SelectByName(pattern)
|
||||
+SelectByColor(hue)
|
||||
+SelectByProperties(filter)
|
||||
+Validate(target)
|
||||
+Enqueue(targets)
|
||||
+ExecuteNext()
|
||||
}
|
||||
class TargetQueue {
|
||||
+Add(target)
|
||||
+Remove(target)
|
||||
+Peek()
|
||||
+Dequeue()
|
||||
+Count
|
||||
}
|
||||
class EntityCollection {
|
||||
+FilteredView(filters)
|
||||
+OrderBy(comparer)
|
||||
+FirstOrDefault(predicate)
|
||||
}
|
||||
class MobileCollection {
|
||||
+Nearby(playerPos, radius)
|
||||
+ByNotoriety(rules)
|
||||
+ByFriends(list)
|
||||
}
|
||||
TargetManager --> TargetQueue : "uses"
|
||||
TargetManager --> EntityCollection : "queries"
|
||||
TargetManager --> MobileCollection : "queries"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
|
||||
### Target Body Data and Enums
|
||||
Selection often relies on predefined body categories and enums:
|
||||
- Body-to-category mapping for creature/item classification
|
||||
- Notoriety and faction enums for friend/enemy logic
|
||||
- Flags and attributes used in property-based filtering
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TargetBodyData {
|
||||
+Map(bodyId) Category
|
||||
+IsCreature(bodyId) bool
|
||||
+IsItem(bodyId) bool
|
||||
}
|
||||
class Enums {
|
||||
<<enumeration>>
|
||||
Notoriety
|
||||
TargetCategory
|
||||
SelectionOrder
|
||||
}
|
||||
TargetBodyData --> Enums : "uses"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
|
||||
### Advanced Targeting Scenarios
|
||||
|
||||
#### Conditional Targeting
|
||||
Use conditions to choose between different target sets depending on state:
|
||||
- If low health, prioritize friendly healers
|
||||
- If no valid enemy, switch to nearest resource node
|
||||
- If line-of-sight fails, fall back to ranged option
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start"]) --> CheckState["Evaluate Conditions"]
|
||||
CheckState --> ConditionA{"Condition A true?"}
|
||||
ConditionA --> |Yes| SetA["Set Criteria A"]
|
||||
ConditionA --> |No| ConditionB{"Condition B true?"}
|
||||
ConditionB --> |Yes| SetB["Set Criteria B"]
|
||||
ConditionB --> |No| Fallback["Fallback Criteria"]
|
||||
SetA --> Select["Select Targets"]
|
||||
SetB --> Select
|
||||
Fallback --> Select
|
||||
Select --> Validate["Validate & Sort"]
|
||||
Validate --> Execute["Execute/Queue"]
|
||||
Execute --> End(["End"])
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
#### Priority-Based Selection
|
||||
Rank candidates using multiple criteria:
|
||||
- Primary: proximity
|
||||
- Secondary: notoriety
|
||||
- Tertiary: resource availability or item quality
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Candidates"]) --> Rank1["Sort by Proximity"]
|
||||
Rank1 --> Rank2["Stable Sort by Notoriety"]
|
||||
Rank2 --> Rank3["Stable Sort by Quality/Availability"]
|
||||
Rank3 --> PickTop["Pick Top Ranked"]
|
||||
PickTop --> Validate["Validate Target"]
|
||||
Validate --> Execute["Execute/Queue"]
|
||||
Execute --> End(["End"])
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
#### Dynamic Target Switching
|
||||
Rotate among valid targets to distribute workload or avoid stale locks:
|
||||
- Maintain a list of eligible targets
|
||||
- On each cycle, pick next candidate
|
||||
- Re-validate before acting
|
||||
- Reset rotation when invalid
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Loop as "Automation Loop"
|
||||
participant TM as "TargetManager"
|
||||
participant Q as "TargetQueue"
|
||||
participant Game as "Game Client"
|
||||
Loop->>TM : Get Next Candidate
|
||||
TM->>TM : Rotate Index
|
||||
TM->>TM : Validate Candidate
|
||||
alt Valid
|
||||
TM->>Q : Enqueue Candidate
|
||||
Q->>Game : Issue Action
|
||||
Game-->>TM : Status
|
||||
else Invalid
|
||||
TM->>TM : Remove From Rotation
|
||||
TM->>Loop : Retry Next
|
||||
end
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
### Examples
|
||||
|
||||
#### Combat Automation
|
||||
- Enemy acquisition by notoriety and distance
|
||||
- Conditional switching if primary target dies or becomes invalid
|
||||
- Fallback to nearest hostile if none found
|
||||
|
||||
#### Resource Gathering
|
||||
- Select by type (resource nodes), color (ore/gems), and distance
|
||||
- Prioritize highest yield or closest node
|
||||
- Fallback to inventory check and vendor if none available
|
||||
|
||||
#### Social Interactions
|
||||
- Friend selection by friend list and proximity
|
||||
- Conditional targeting based on chat presence or party status
|
||||
- Fallback to last known friend if current unavailable
|
||||
|
||||
[No sources needed since these examples illustrate usage patterns without analyzing specific files]
|
||||
|
||||
### Target Validation, Timeouts, and Fallbacks
|
||||
- Validation checks include existence, visibility, range, and game-state constraints
|
||||
- Timeout handling prevents macros from hanging indefinitely when targets disappear
|
||||
- Fallback strategies ensure continuity: alternate targets, change criteria, or abort gracefully
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Select Target"]) --> Validate["Validate Target"]
|
||||
Validate --> Valid{"Valid?"}
|
||||
Valid --> |Yes| Proceed["Proceed to Action"]
|
||||
Valid --> |No| TimeoutCheck{"Timeout Reached?"}
|
||||
TimeoutCheck --> |Yes| Fallback["Apply Fallback Strategy"]
|
||||
TimeoutCheck --> |No| Retry["Retry With Adjusted Criteria"]
|
||||
Retry --> Validate
|
||||
Fallback --> End(["Exit or Continue"])
|
||||
Proceed --> End
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
**Section sources**
|
||||
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram highlights key dependencies among targeting components and entity collections.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
TAC["TargetAcquisitionEnemy.cs"] --> TM["TargetManager.cs"]
|
||||
TAF["TargetAcquisitionFriend.cs"] --> TM
|
||||
TGT["Targeting.cs"] --> TM
|
||||
MC["TargetCommands.cs"] --> TM
|
||||
TM --> TQ["TargetQueue.cs"]
|
||||
TM --> EC["EntityCollection.cs"]
|
||||
TM --> MCOL["MobileCollection.cs"]
|
||||
MCOL --> MOB["Mobile.cs"]
|
||||
MOB --> ENT["Entity.cs"]
|
||||
TM --> ENUMS["Enums.cs"]
|
||||
TM --> BODY["TargetBodyData.cs"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
|
||||
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
|
||||
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
|
||||
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
|
||||
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
|
||||
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
|
||||
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
|
||||
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
|
||||
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
|
||||
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
|
||||
|
||||
## Performance Considerations
|
||||
When working with large entity collections:
|
||||
- Prefer filtered views and early pruning (distance, notoriety, type) to reduce candidate sets
|
||||
- Use stable multi-criteria sorting to minimize re-scans
|
||||
- Avoid repeated allocations; reuse comparators and filter objects where possible
|
||||
- Batch enqueue operations instead of issuing individual actions per candidate
|
||||
- Implement timeouts and short-circuit evaluation to prevent long-running selections
|
||||
- Monitor memory pressure by limiting retained references to transient candidates
|
||||
|
||||
Best practices:
|
||||
- Cache frequently used filters and comparators
|
||||
- Limit search radius for nearby queries
|
||||
- Defer expensive property checks until necessary
|
||||
- Use queues to decouple selection from execution
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- No targets found: Verify filters (type, color, name), distance radius, and notoriety settings
|
||||
- Stale targets: Ensure validation runs before each action and implement rotation/reset logic
|
||||
- Lag spikes: Reduce collection size via tighter filters; avoid heavy computations in hot paths
|
||||
- Inconsistent behavior: Add logging around selection steps and timeouts; confirm game state changes
|
||||
|
||||
Diagnostic tips:
|
||||
- Inspect candidate counts after each filter stage
|
||||
- Log reasons for rejection (out of range, invalid notoriety, missing properties)
|
||||
- Confirm queue depth and execution timing
|
||||
|
||||
**Section sources**
|
||||
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.cs)
|
||||
|
||||
## Conclusion
|
||||
The targeting subsystem combines flexible filtering, prioritization, and queue-driven execution to support robust automation across combat, gathering, and social interactions. By applying conditional logic, priority ranking, and strong validation with timeouts and fallbacks, macros can remain responsive and efficient even under heavy load. Adhering to performance best practices ensures smooth operation with large entity collections and minimizes memory overhead.
|
||||
@@ -0,0 +1,402 @@
|
||||
# Utility Commands
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.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 utility commands available in the ClassicAssist.Avalonia macro system, focusing on timing controls, conditional logic, loops, variable management, and debugging utilities. It provides parameter specifications for timers, conditions, iteration patterns, and data storage, along with examples of complex automation flows, error handling, logging, and performance monitoring. The goal is to help you build robust, maintainable macros that execute reliably under game conditions.
|
||||
|
||||
## Project Structure
|
||||
The macro command implementations live in the shared module under Data/Macros/Commands. Timer-related commands are implemented in a dedicated file, while the macro execution engine and supporting utilities (logging, threading primitives, timing helpers) are spread across related files. Tests validate timer behavior and integration points.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared Macro System"
|
||||
A["TimerCommands.cs"]
|
||||
B["MacroInvoker.cs"]
|
||||
C["MacroManager.cs"]
|
||||
D["SystemMessageTextWriter.cs"]
|
||||
E["ParameterType.cs"]
|
||||
F["OffsetStopwatch.cs"]
|
||||
G["ThreadQueue.cs"]
|
||||
H["ThreadPriorityQueue.cs"]
|
||||
end
|
||||
subgraph "Tests"
|
||||
T["TimerTests.cs"]
|
||||
end
|
||||
A --> B
|
||||
B --> C
|
||||
B --> D
|
||||
B --> E
|
||||
B --> F
|
||||
B --> G
|
||||
B --> H
|
||||
T --> A
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
|
||||
## Core Components
|
||||
- Timer commands: Provide scheduling, delays, and periodic execution hooks used by macros to coordinate actions over time.
|
||||
- Macro invoker: Executes macro commands, manages parameters, and coordinates with logging and threading primitives.
|
||||
- Macro manager: Hosts and orchestrates macro instances, including lifecycle and dispatching.
|
||||
- Logging writer: Routes macro output to the in-game system message channel for visibility.
|
||||
- Parameter types: Define supported argument types for commands and their parsing rules.
|
||||
- Timing utilities: High-resolution timing helpers for accurate delays and intervals.
|
||||
- Threading queues: Priority and FIFO queues used to schedule work items safely across threads.
|
||||
|
||||
Key responsibilities:
|
||||
- TimerCommands.cs: Implements timer-related operations exposed to macros.
|
||||
- MacroInvoker.cs: Parses parameters, resolves command handlers, and executes them within the macro context.
|
||||
- MacroManager.cs: Manages macro registration, discovery, and runtime control.
|
||||
- SystemMessageTextWriter.cs: Bridges macro logs to the UI/game messages.
|
||||
- OffsetStopwatch.cs: Provides precise elapsed time measurements.
|
||||
- ThreadQueue.cs / ThreadPriorityQueue.cs: Provide thread-safe queuing for scheduled tasks.
|
||||
|
||||
**Section sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The macro system exposes commands to scripts/macros. Timer commands integrate with the macro invoker and underlying timing and queueing infrastructure to schedule work. Logging is routed through a writer that integrates with the application’s message channels.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant M as "Macro"
|
||||
participant Inv as "MacroInvoker"
|
||||
participant TC as "TimerCommands"
|
||||
participant Q as "ThreadQueue/PriorityQueue"
|
||||
participant SW as "SystemMessageTextWriter"
|
||||
M->>Inv : Invoke("timer", args)
|
||||
Inv->>TC : Execute timer operation
|
||||
TC->>Q : Schedule task/delay
|
||||
Q-->>TC : Task queued
|
||||
TC-->>Inv : Status/result
|
||||
Inv->>SW : Log status/info
|
||||
SW-->>M : Visible in game/system messages
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Timer Commands
|
||||
Timer commands enable macros to delay execution, schedule one-shot or recurring tasks, and synchronize with external events. They rely on high-resolution timing and thread-safe queues to ensure predictable behavior.
|
||||
|
||||
- Scheduling model:
|
||||
- One-shot delays: Execute a callback after a specified duration.
|
||||
- Periodic tasks: Repeatedly execute a callback at fixed intervals until cancelled.
|
||||
- Cancellation: Support stopping scheduled tasks when macros terminate or explicitly cancel.
|
||||
- Time units:
|
||||
- Durations are expressed in milliseconds; use integer values for precision.
|
||||
- Concurrency:
|
||||
- Tasks are enqueued into priority or FIFO queues and executed on appropriate threads.
|
||||
- Error handling:
|
||||
- Exceptions inside scheduled callbacks should be caught and logged via the system message writer to avoid crashing the macro runtime.
|
||||
- Performance:
|
||||
- Prefer batching small tasks and avoiding excessive short-interval timers to reduce overhead.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Start"]) --> ParseArgs["Parse arguments<br/>duration(ms), repeat?, interval(ms)"]
|
||||
ParseArgs --> Validate{"Valid inputs?"}
|
||||
Validate --> |No| LogError["Log error via SystemMessageTextWriter"]
|
||||
Validate --> |Yes| CreateTask["Create task entry"]
|
||||
CreateTask --> QueueType{"Periodic?"}
|
||||
QueueType --> |No| EnqueueOneShot["Enqueue one-shot delay"]
|
||||
QueueType --> |Yes| EnqueuePeriodic["Enqueue periodic interval"]
|
||||
EnqueueOneShot --> Done(["Done"])
|
||||
EnqueuePeriodic --> Done
|
||||
LogError --> Done
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
### Conditional Logic
|
||||
Conditional logic in macros typically evaluates expressions and branches execution based on results. While specific condition commands may be defined elsewhere, the invoker parses parameters and delegates evaluation to command handlers.
|
||||
|
||||
- Expression evaluation:
|
||||
- Supports numeric comparisons, string equality, and boolean flags.
|
||||
- Type safety:
|
||||
- Uses ParameterType definitions to coerce and validate inputs before evaluation.
|
||||
- Short-circuiting:
|
||||
- Logical operators can short-circuit to optimize performance.
|
||||
- Debugging:
|
||||
- Use logging to print intermediate values during development.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Entry(["Evaluate Condition"]) --> Parse["Parse operands and operator"]
|
||||
Parse --> Coerce["Coerce types using ParameterType"]
|
||||
Coerce --> Eval["Evaluate expression"]
|
||||
Eval --> Branch{"True?"}
|
||||
Branch --> |Yes| ThenBranch["Execute then-block"]
|
||||
Branch --> |No| ElseBranch["Execute else-block"]
|
||||
ThenBranch --> Exit(["Exit"])
|
||||
ElseBranch --> Exit
|
||||
```
|
||||
|
||||
[No diagram sources since this section describes conceptual flow without mapping to specific files]
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
|
||||
### Loops
|
||||
Loops allow repeated execution of blocks until a condition changes or a count is reached.
|
||||
|
||||
- For-style loops:
|
||||
- Iterate a fixed number of times with an index variable.
|
||||
- While-style loops:
|
||||
- Repeat while a condition remains true; include safeguards against infinite loops.
|
||||
- Break and continue:
|
||||
- Control flow keywords to exit early or skip iterations.
|
||||
- Performance:
|
||||
- Avoid heavy operations inside tight loops; batch I/O and minimize allocations.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Init(["Initialize loop variables"]) --> CheckCond["Check loop condition"]
|
||||
CheckCond --> |False| EndLoop(["Exit loop"])
|
||||
CheckCond --> |True| Body["Execute loop body"]
|
||||
Body --> Update["Update loop variables"]
|
||||
Update --> CheckCond
|
||||
```
|
||||
|
||||
[No diagram sources since this section describes conceptual flow without mapping to specific files]
|
||||
|
||||
**Section sources**
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
### Variable Management
|
||||
Variables store state across macro executions and between commands.
|
||||
|
||||
- Scope:
|
||||
- Local variables scoped to the current macro instance.
|
||||
- Global variables accessible across macros if explicitly designed.
|
||||
- Types:
|
||||
- Integers, strings, booleans, and collections as supported by ParameterType.
|
||||
- Operations:
|
||||
- Set, get, increment/decrement, and list variables.
|
||||
- Persistence:
|
||||
- Optional persistence to configuration or profile storage for long-term state.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MacroContext {
|
||||
+SetVariable(name, value)
|
||||
+GetVariable(name) object
|
||||
+ListVariables() IEnumerable
|
||||
}
|
||||
class ParameterType {
|
||||
+Int
|
||||
+String
|
||||
+Boolean
|
||||
+Collection
|
||||
}
|
||||
MacroContext --> ParameterType : "uses for coercion"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ParameterType.cs](file://ClassicAssist.Shared/Data/Macros/ParameterType.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
### Debugging Utilities
|
||||
Debugging utilities provide logging, inspection, and diagnostics to aid macro development.
|
||||
|
||||
- Logging:
|
||||
- Write messages to the in-game system channel via SystemMessageTextWriter.
|
||||
- Inspection:
|
||||
- Dump variables, counters, and internal state for troubleshooting.
|
||||
- Timing metrics:
|
||||
- Use OffsetStopwatch to measure durations of critical sections.
|
||||
- Test coverage:
|
||||
- Unit tests validate timer behavior and edge cases.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as "Developer"
|
||||
participant Macro as "Macro"
|
||||
participant Inv as "MacroInvoker"
|
||||
participant Log as "SystemMessageTextWriter"
|
||||
participant Sw as "OffsetStopwatch"
|
||||
Dev->>Macro : Run macro with debug statements
|
||||
Macro->>Inv : Log("debug info")
|
||||
Inv->>Log : Write message
|
||||
Macro->>Sw : Start measurement
|
||||
Macro->>Macro : Perform operation
|
||||
Macro->>Sw : Stop measurement
|
||||
Macro->>Log : Log elapsed time
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The macro system exhibits clear separation of concerns:
|
||||
- TimerCommands depends on the invoker for parameter parsing and on queues for scheduling.
|
||||
- MacroInvoker depends on ParameterType for input validation and on SystemMessageTextWriter for logging.
|
||||
- OffsetStopwatch provides timing accuracy for both timers and performance measurements.
|
||||
- Tests depend on TimerCommands to assert expected behaviors.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Timer["TimerCommands.cs"] --> Invoker["MacroInvoker.cs"]
|
||||
Timer --> Q1["ThreadQueue.cs"]
|
||||
Timer --> Q2["ThreadPriorityQueue.cs"]
|
||||
Invoker --> Params["ParameterType.cs"]
|
||||
Invoker --> Log["SystemMessageTextWriter.cs"]
|
||||
Invoker --> Stop["OffsetStopwatch.cs"]
|
||||
Tests["TimerTests.cs"] --> Timer
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [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)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
|
||||
**Section sources**
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [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)
|
||||
- [OffsetStopwatch.cs](file://ClassicAssist.Shared/Misc/OffsetStopwatch.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Minimize timer granularity:
|
||||
- Avoid very short intervals unless necessary; prefer coarser intervals and batching.
|
||||
- Reduce allocations:
|
||||
- Reuse objects where possible and avoid creating large temporary structures inside loops.
|
||||
- Efficient logging:
|
||||
- Batch log messages and avoid excessive verbosity in production runs.
|
||||
- Queue selection:
|
||||
- Use priority queues for urgent tasks and FIFO for background work to balance responsiveness and throughput.
|
||||
- Measurement:
|
||||
- Use OffsetStopwatch to identify hotspots and validate improvements.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Timers not firing:
|
||||
- Verify queue availability and thread pool health; check for exceptions in scheduled callbacks.
|
||||
- Delays too long or too short:
|
||||
- Confirm unit conversions and ensure millisecond values are correct.
|
||||
- Memory growth:
|
||||
- Inspect variable scopes and ensure cleanup of scheduled tasks upon macro termination.
|
||||
- Logging missing:
|
||||
- Ensure SystemMessageTextWriter is initialized and permissions allow writing messages.
|
||||
- Flaky conditions:
|
||||
- Add logging around condition evaluations and consider debouncing rapid state changes.
|
||||
|
||||
Validation references:
|
||||
- Timer behavior assertions and edge cases are covered by tests.
|
||||
|
||||
**Section sources**
|
||||
- [TimerTests.cs](file://ClassicAssist.Tests/MacroCommands/TimerTests.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [ThreadQueue.cs](file://ClassicAssist.Shared/Misc/ThreadQueue.cs)
|
||||
- [ThreadPriorityQueue.cs](file://ClassicAssist.Shared/Misc/ThreadPriorityQueue.cs)
|
||||
|
||||
## Conclusion
|
||||
The utility commands in the ClassicAssist.Avalonia macro system provide robust timing, conditional logic, looping, variable management, and debugging capabilities. By leveraging the timer commands, parameter typing, logging, and timing utilities, you can construct reliable automations that are easy to test and maintain. Follow best practices for organization, reuse, and performance to keep macros responsive and resilient.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Best Practices for Macro Organization
|
||||
- Modularize logic:
|
||||
- Split complex workflows into reusable sub-macros invoked by name.
|
||||
- Centralize constants:
|
||||
- Store durations, thresholds, and identifiers in a single place for consistency.
|
||||
- Defensive programming:
|
||||
- Validate inputs, handle exceptions, and log meaningful messages.
|
||||
- Testing:
|
||||
- Write unit tests for critical paths, especially timers and conditions.
|
||||
- Documentation:
|
||||
- Comment non-obvious logic and maintain a changelog for macro versions.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
Reference in New Issue
Block a user