# Macro Commands

<cite>
**Referenced Files in This Document**
- [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)
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.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)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.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 a detailed reference for built-in macro commands available to Python scripts in ClassicAssist. It covers command categories including ActionCommands for basic operations, MovementCommands for navigation, TargetCommands for entity targeting, SpellCommands for magic system interaction, MobileCommands for character manipulation, and ObjectCommands for item handling. For each command, it documents method signatures, parameters, return values, error conditions, usage examples, chaining patterns, conditional logic integration, performance tips, registration process, and custom command development guidelines.

## Project Structure
The macro command system is organized under Shared with clear separation between command implementations, invocation infrastructure, and display attributes. The primary areas relevant to this reference are:
- Command implementations grouped by category under Data/Macros/Commands
- Invocation and management under Data/Macros
- Hotkey command attribute and related utilities under Data/Hotkeys/Commands
- Display and help metadata under Data/Macros and Resources

```mermaid
graph TB
subgraph "Shared"
subgraph "Data/Macros/Commands"
A["ActionCommands.cs"]
B["MovementCommands.cs"]
C["TargetCommands.cs"]
D["SpellCommands.cs"]
E["MobileCommands.cs"]
F["ObjectCommands.cs"]
end
subgraph "Data/Macros"
G["MacroInvoker.cs"]
H["MacroManager.cs"]
I["ParameterType.cs"]
J["CommandsDisplayAttribute.cs"]
end
subgraph "Data/Hotkeys/Commands"
K["HotkeyCommandAttribute.cs"]
end
end
A --> G
B --> G
C --> G
D --> G
E --> G
F --> G
G --> H
J --> G
K --> G
```

**Diagram sources**
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.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)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)

**Section sources**
- [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)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)

## Core Components
- MacroInvoker: Executes macro commands from Python scripts, resolves command names, validates parameters, and dispatches to command handlers.
- MacroManager: Manages macro entries, loading, saving, and lifecycle; integrates with UI and hotkeys.
- ParameterType: Defines supported parameter types for command parsing and validation.
- CommandsDisplayAttribute: Provides help text and categorization for commands in UI and help systems.
- HotkeyCommandAttribute: Enables binding commands to hotkeys and exposes them to the hotkey system.

Key responsibilities:
- Command discovery and registration
- Parameter parsing and type coercion
- Error reporting and logging
- Integration with game engine services (targeting, spells, movement, objects, mobiles)

**Section sources**
- [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)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)

## Architecture Overview
The macro command architecture follows a layered approach:
- Python script layer calls macro commands via exposed methods
- MacroInvoker parses and validates inputs, then delegates to specific command classes
- Command classes interact with game subsystems (Targeting, Spells, Movement, Objects, Mobiles)
- Results and errors are returned to the script context

```mermaid
sequenceDiagram
participant Script as "Python Script"
participant Invoker as "MacroInvoker"
participant Cmd as "Command Class"
participant Engine as "Game Subsystems"
Script->>Invoker : Call command(name, params)
Invoker->>Invoker : Parse and validate parameters
Invoker->>Cmd : Dispatch to handler
Cmd->>Engine : Request action/query
Engine-->>Cmd : Result or error
Cmd-->>Invoker : Return value/status
Invoker-->>Script : Response or exception
```

**Diagram sources**
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)

## Detailed Component Analysis

### ActionCommands
Purpose: Basic operations such as chat messaging, delays, condition checks, and utility functions commonly used in macros.

Typical capabilities:
- Send messages to chat or system channels
- Introduce delays and pauses
- Evaluate conditions and control flow helpers
- Access global state and environment variables

Method signature pattern:
- Method name corresponds to command alias
- Parameters typed according to ParameterType
- Returns boolean or string depending on operation
- Throws exceptions on invalid input or runtime errors

Error conditions:
- Invalid parameter types or out-of-range values
- Network timeouts when interacting with server
- Permission restrictions for certain actions

Usage example references:
- See [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Combine delay and message commands to sequence events
- Use condition checks to branch macro flows

Conditional logic integration:
- Use helper methods to evaluate game state before issuing actions

Performance tips:
- Batch small operations where possible
- Avoid excessive polling loops; use event-driven triggers when available

**Section sources**
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)

### MovementCommands
Purpose: Navigation and positioning commands for moving the player character.

Typical capabilities:
- Move in cardinal directions
- Pathfinding-based movement
- Stop movement
- Query current position and facing direction

Method signature pattern:
- Directional methods accept enum or string direction
- Pathfinding methods accept destination coordinates or target object
- Return success/failure status

Error conditions:
- Obstacles blocking path
- Server-side movement validation failures
- Invalid coordinates or targets

Usage example references:
- See [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Sequence multiple moves to reach waypoints
- Combine stop and look commands to confirm arrival

Conditional logic integration:
- Check distance or line-of-sight before moving

Performance tips:
- Prefer direct directional commands over complex pathfinding when feasible
- Debounce rapid movement requests to reduce network overhead

**Section sources**
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)

### TargetCommands
Purpose: Entity targeting operations for selecting characters, items, or ground locations.

Typical capabilities:
- Target by ID, name, or proximity
- Clear current target
- Retrieve targeted entity details
- Validate target validity and permissions

Method signature pattern:
- Methods accept IDs, names, or filters
- Return target entity reference or null
- Throw exceptions on ambiguous or invalid targets

Error conditions:
- Multiple matches without disambiguation
- Target not in range or not valid
- Insufficient permissions to target

Usage example references:
- See [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Chain target selection followed by spell casting or item use
- Use conditional checks to ensure target validity before proceeding

Conditional logic integration:
- Filter entities by type, color, or properties prior to targeting

Performance tips:
- Cache frequently accessed target data
- Minimize repeated queries by reusing entity references

**Section sources**
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)

### SpellCommands
Purpose: Magic system interaction including spell casting, queue management, and spell information retrieval.

Typual capabilities:
- Cast spells by name or rune
- Manage spellcasting queue
- Query mana levels and skill requirements
- Interrupt ongoing casts

Method signature pattern:
- Cast methods accept spell identifiers and optional parameters
- Queue methods manage pending casts
- Return success/failure or cast handle

Error conditions:
- Insufficient mana or skill level
- Invalid spell or cooldown active
- Targeting conflicts or invalid targets

Usage example references:
- See [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Sequence multiple spells with delays and checks
- Combine targeting and casting in one workflow

Conditional logic integration:
- Check mana and skill thresholds before casting
- Handle interrupts and cancellations gracefully

Performance tips:
- Avoid spamming cast attempts; respect server response timing
- Use queue management to batch spells efficiently

**Section sources**
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)

### MobileCommands
Purpose: Character manipulation and mobile entity interactions.

Typical capabilities:
- Query mobile stats and skills
- Toggle mounts and abilities
- Interact with other mobiles (trade, follow, etc.)
- Control character states (combat mode, war mode)

Method signature pattern:
- Methods accept mobile IDs or references
- Return status codes or mobile data structures
- Throw exceptions on invalid mobile references

Error conditions:
- Mobile not found or out of range
- Permission denied for interactions
- State conflicts (e.g., cannot mount while engaged)

Usage example references:
- See [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Combine stat checks with ability toggles
- Sequence mount/unmount with movement commands

Conditional logic integration:
- Verify combat state before performing sensitive actions

Performance tips:
- Reduce frequent stat polling; cache results when safe
- Use event-driven updates instead of tight loops

**Section sources**
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)

### ObjectCommands
Purpose: Item handling and container operations.

Typical capabilities:
- Use items in hand or containers
- Drop, equip, or move items
- Inspect item properties and contents
- Manage inventory and backpack organization

Method signature pattern:
- Methods accept item IDs, container references, or filters
- Return success/failure or item references
- Throw exceptions on invalid items or insufficient permissions

Error conditions:
- Item not present or locked
- Container full or inaccessible
- Property access denied

Usage example references:
- See [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs) for concrete methods and behavior.

Chaining patterns:
- Chain inspect-use-drop sequences
- Combine container traversal with item filtering

Conditional logic integration:
- Check item durability or charges before using
- Validate container capacity before dropping

Performance tips:
- Batch container operations to minimize packet overhead
- Reuse item references across commands to avoid repeated lookups

**Section sources**
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)

### Conceptual Overview
The following conceptual diagram illustrates how macro commands integrate with the broader system:

```mermaid
flowchart TD
Start(["Macro Execution"]) --> Parse["Parse Command and Parameters"]
Parse --> Validate{"Valid Input?"}
Validate --> |No| Error["Return Error"]
Validate --> |Yes| Dispatch["Dispatch to Command Handler"]
Dispatch --> GameOps["Interact with Game Systems"]
GameOps --> Result{"Operation Success?"}
Result --> |No| HandleErr["Handle Errors and Retry/Fallback"]
Result --> |Yes| ReturnVal["Return Value to Script"]
HandleErr --> ReturnVal
ReturnVal --> End(["End"])
```

[No sources needed since this diagram shows conceptual workflow, not actual code structure]

## Dependency Analysis
Command classes depend on shared infrastructure for invocation, parameter handling, and display metadata. They also rely on game subsystems for actual operations.

```mermaid
classDiagram
class MacroInvoker {
+Execute(commandName, parameters)
+ValidateParameters(parameters)
+ResolveHandler(commandName)
}
class MacroManager {
+LoadMacros()
+SaveMacros()
+RunMacro(macroId)
}
class ParameterType {
<<enum>>
}
class CommandsDisplayAttribute {
+HelpText
+Category
}
class HotkeyCommandAttribute {
+KeyName
+Description
}
class ActionCommands
class MovementCommands
class TargetCommands
class SpellCommands
class MobileCommands
class ObjectCommands
MacroInvoker --> ActionCommands : "dispatches"
MacroInvoker --> MovementCommands : "dispatches"
MacroInvoker --> TargetCommands : "dispatches"
MacroInvoker --> SpellCommands : "dispatches"
MacroInvoker --> MobileCommands : "dispatches"
MacroInvoker --> ObjectCommands : "dispatches"
MacroInvoker --> ParameterType : "uses"
MacroInvoker --> CommandsDisplayAttribute : "reads metadata"
MacroInvoker --> HotkeyCommandAttribute : "binds to hotkeys"
MacroManager --> MacroInvoker : "invokes"
```

**Diagram sources**
- [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)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.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)
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)

**Section sources**
- [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)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)

## Performance Considerations
- Minimize redundant queries by caching entity and item references
- Use batching for container operations and bulk movements
- Respect server timing; avoid tight loops and excessive polling
- Leverage event-driven updates rather than manual refresh cycles
- Prefer direct commands over complex pathfinding when possible
- Implement backoff and retry strategies for transient failures

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- Parameter validation errors: Ensure correct types and ranges per ParameterType
- Target resolution failures: Disambiguate by ID or refine filters
- Spell casting failures: Check mana, skill levels, and cooldowns
- Movement blocked: Verify obstacles and server-side constraints
- Object access denied: Confirm ownership and permissions

Diagnostic steps:
- Enable verbose logging in MacroInvoker to trace command execution
- Inspect error messages and stack traces for root causes
- Validate command availability and registration status
- Test commands individually to isolate failures

**Section sources**
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)

## Conclusion
The macro command system provides a robust and extensible interface for automating gameplay through Python scripts. By understanding command categories, method signatures, error conditions, and best practices, users can build efficient and reliable automation workflows. Proper registration and adherence to performance guidelines ensure smooth integration with the game engine and responsive macro execution.

[No sources needed since this section summarizes without analyzing specific files]

## Appendices

### Command Registration Process
- Commands are discovered and registered via reflection and attributes
- MacroInvoker resolves command names to handlers at runtime
- Display attributes provide help text and categorization for UI
- Hotkey attributes enable binding commands to keyboard shortcuts

Development guidelines:
- Follow consistent naming conventions for methods and parameters
- Use ParameterType to define expected input types
- Provide meaningful error messages and return codes
- Document commands with CommandsDisplayAttribute for discoverability
- Test commands thoroughly across edge cases and failure modes

**Section sources**
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
- [CommandsDisplayAttribute.cs](file://ClassicAssist.Shared/Data/Macros/CommandsDisplayAttribute.cs)
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)