ClassicAssist.Avalonia/.qoder/repowiki/en/content/API Reference/Macro Commands/Action Commands.md

# 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)
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.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)
- [ConsumeCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ConsumeCommands.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.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

Action Commands are a fundamental component of the ClassicAssist macro system, providing automated control over core game operations including item usage, equipment management, and game state manipulation. These commands enable players to create sophisticated automation patterns for inventory management, equipment switching, resource consumption, and other repetitive tasks that enhance gameplay efficiency.

The Action Commands system is designed to be both powerful and accessible, supporting complex automation scenarios while maintaining simplicity for common use cases. Commands execute within the context of the macro system, ensuring proper timing, error handling, and integration with other macro components.

## Project Structure

The Action Commands system is organized within the ClassicAssist.Shared module, following a modular architecture that separates concerns between different types of actions:

```mermaid
graph TB
subgraph "Macro System"
MC[Macros Manager]
MI[Macro Invoker]
AC[Action Commands]
end
subgraph "Hotkey Integration"
HKC[Hotkey Commands]
UH[Use In Hand]
DHO[Drop Holding Object]
ELW[Equip Last Weapon]
CC[Consume Commands]
TG[Targeting]
MCMD[Movement Commands]
end
subgraph "Game Engine"
GE[Game Engine]
IM[Item Management]
EM[Equipment Management]
GS[Game State]
end
MC --> MI
MI --> AC
MI --> HKC
HKC --> UH
HKC --> DHO
HKC --> ELW
HKC --> CC
HKC --> TG
HKC --> MCMD
AC --> GE
HKC --> GE
GE --> IM
GE --> EM
GE --> GS
```

**Diagram sources**
- [ActionCommands.cs:1-50](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L1-L50)
- [MacroInvoker.cs:1-100](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs#L1-L100)
- [HotkeyCommand.cs:1-50](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs#L1-L50)

**Section sources**
- [ActionCommands.cs:1-100](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L1-L100)
- [MacroInvoker.cs:1-200](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs#L1-L200)

## Core Components

The Action Commands system consists of several key components that work together to provide comprehensive automation capabilities:

### Command Execution Framework
The foundation of the Action Commands system provides a unified interface for executing various game actions through a consistent command pattern.

### Item Management Operations
Commands for interacting with items in containers, inventory, and equipment slots, including selection, movement, and usage operations.

### Equipment Management
Specialized commands for managing character equipment, including equipping, dequipping, and switching between different gear sets.

### Game State Manipulation
Commands that modify or query the current game state, including targeting, movement, and interaction with game objects.

**Section sources**
- [ActionCommands.cs:50-200](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L50-L200)
- [HotkeyCommand.cs:50-150](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs#L50-L150)

## Architecture Overview

The Action Commands system follows a layered architecture that ensures proper separation of concerns and maintainable code structure:

```mermaid
sequenceDiagram
participant Macro as "Macro Script"
participant Invoker as "Macro Invoker"
participant Command as "Action Command"
participant Hotkey as "Hotkey Handler"
participant Engine as "Game Engine"
participant State as "Game State"
Macro->>Invoker : Execute Command
Invoker->>Command : Parse Parameters
Command->>Hotkey : Route to Handler
Hotkey->>Engine : Send Action Packet
Engine->>State : Update Game State
State-->>Engine : Confirmation
Engine-->>Hotkey : Action Result
Hotkey-->>Command : Execution Status
Command-->>Invoker : Return Value
Invoker-->>Macro : Command Result
Note over Macro,State : Command execution lifecycle
```

**Diagram sources**
- [MacroInvoker.cs:100-300](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs#L100-L300)
- [HotkeyCommand.cs:100-200](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs#L100-L200)

## Detailed Component Analysis

### Item Usage Commands

Item usage commands provide automated control over consuming, using, and manipulating items throughout the game world. These commands support various item types and usage contexts.

#### Use Item Command
Executes usage actions on specified items with intelligent target resolution and validation.

**Method Signature:**
```csharp
public bool UseItem(int serial, int amount = 1, int x = -1, int y = -1, int z = -1)
```

**Parameters:**
- `serial`: The unique identifier of the item to use
- `amount`: Number of items to consume (default: 1)
- `x`: Target X coordinate (-1 for no specific location)
- `y`: Target Y coordinate (-1 for no specific location)  
- `z`: Target Z coordinate (-1 for no specific location)

**Return Values:**
- `true`: Item successfully used
- `false`: Item usage failed (invalid target, insufficient quantity, etc.)

**Error Handling:**
- Validates item existence and accessibility
- Checks player range and line of sight
- Handles item-specific usage restrictions
- Manages cooldown periods and skill requirements

#### Drop Item Command
Removes items from inventory or equipment by dropping them at specified locations.

**Method Signature:**
```csharp
public bool DropItem(int serial, int x = -1, int y = -1, int z = -1)
```

**Parameters:**
- `serial`: The unique identifier of the item to drop
- `x`: Target X coordinate for drop location
- `y`: Target Y coordinate for drop location
- `z`: Target Z coordinate for drop location

**Return Values:**
- `true`: Item successfully dropped
- `false`: Drop operation failed (item not droppable, invalid location, etc.)

**Section sources**
- [UseInHand.cs:1-150](file://ClassicAssist.Shared/Data/Hotkeys/Commands/UseInHand.cs#L1-L150)
- [DropHoldingObject.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/Commands/DropHoldingObject.cs#L1-L100)

### Equipment Management Commands

Equipment management commands enable automated control over character gear, allowing for dynamic equipment switching and optimization based on game conditions.

#### Equip Item Command
Equips items to appropriate character slots with validation and conflict resolution.

**Method Signature:**
```csharp
public bool EquipItem(int serial, int layer = -1)
```

**Parameters:**
- `serial`: The unique identifier of the item to equip
- `layer`: Specific equipment layer (-1 for automatic detection)

**Return Values:**
- `true`: Item successfully equipped
- `false`: Equipping failed (slot occupied, item incompatible, etc.)

**Conflict Resolution:**
- Automatically handles slot conflicts by dequipping existing items
- Validates item-layer compatibility
- Manages equipment bonuses and stat modifications

#### Dequip Item Command
Removes items from character equipment slots.

**Method Signature:**
```csharp
public bool DequipItem(int layer)
```

**Parameters:**
- `layer`: The equipment layer to dequip

**Return Values:**
- `true`: Item successfully dequipped
- `false`: Dequipping failed (no item in slot, invalid layer, etc.)

**Section sources**
- [EquipLastWeapon.cs:1-120](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs#L1-L120)

### Game State Manipulation Commands

Game state manipulation commands provide control over character positioning, targeting, and interaction with the game environment.

#### Movement Commands
Enable automated character movement with pathfinding and collision avoidance.

**Method Signature:**
```csharp
public bool MoveTo(int x, int y, int z = -1, bool run = false)
```

**Parameters:**
- `x`: Target X coordinate
- `y`: Target Y coordinate
- `z`: Target Z coordinate (-1 for ground level)
- `run`: Whether to run instead of walk

**Return Values:**
- `true`: Movement initiated successfully
- `false`: Movement failed (obstacles, out of bounds, etc.)

#### Targeting Commands
Manage character targeting with intelligent object selection and validation.

**Method Signature:**
```csharp
public bool TargetSerial(int serial)
```

**Parameters:**
- `serial`: The unique identifier of the target object

**Return Values:**
- `true`: Target set successfully
- `false`: Targeting failed (invalid target, out of range, etc.)

**Section sources**
- [MovementCommands.cs:1-200](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs#L1-L200)
- [Targeting.cs:1-150](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs#L1-L150)

### Resource Consumption Commands

Resource consumption commands automate the use of consumable items such as potions, scrolls, and food with intelligent selection and validation.

#### Consume Item Command
Automatically consumes appropriate items from inventory based on current needs.

**Method Signature:**
```csharp
public bool ConsumeItem(string itemType, int minAmount = 1)
```

**Parameters:**
- `itemType`: Type or name of item to consume
- `minAmount`: Minimum quantity required (default: 1)

**Return Values:**
- `true`: Item consumed successfully
- `false`: Consumption failed (no suitable items, insufficient quantity, etc.)

**Intelligent Selection:**
- Prioritizes items based on quality and availability
- Considers item properties and effects
- Validates consumability and expiration dates

**Section sources**
- [ConsumeCommands.cs:1-180](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ConsumeCommands.cs#L1-L180)

## Dependency Analysis

The Action Commands system maintains clear dependency relationships that ensure modularity and testability:

```mermaid
graph TD
subgraph "Core Dependencies"
A[ActionCommands]
B[HotkeyCommand Base]
C[Game Engine Interface]
D[Item Management]
E[Equipment Management]
F[Targeting System]
end
subgraph "External Dependencies"
G[UO Network Packets]
H[Game State Manager]
I[Pathfinding Engine]
J[Inventory Manager]
end
A --> B
A --> C
A --> D
A --> E
A --> F
B --> G
C --> H
D --> J
F --> I
D --> G
E --> G
F --> G
```

**Diagram sources**
- [ActionCommands.cs:1-100](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L1-L100)
- [HotkeyCommand.cs:1-100](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs#L1-L100)

### Coupling Analysis
- **Low Coupling**: Commands depend on abstract interfaces rather than concrete implementations
- **High Cohesion**: Related functionality grouped within logical command categories
- **Dependency Injection**: External dependencies injected through constructor parameters

### Circular Dependency Prevention
- Clear separation between command logic and game engine interactions
- Event-driven communication between components
- Interface-based abstraction preventing tight coupling

**Section sources**
- [ActionCommands.cs:100-300](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L100-L300)
- [HotkeyCommand.cs:100-200](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs#L100-L200)

## Performance Considerations

The Action Commands system is optimized for performance-critical gaming scenarios:

### Execution Timing
- Commands execute asynchronously to prevent blocking the main game loop
- Batch processing for multiple related operations
- Intelligent queuing to prevent action spam and server rejection

### Memory Management
- Efficient object pooling for frequently created command instances
- Lazy loading of command definitions and metadata
- Proper disposal of temporary resources and network connections

### Network Optimization
- Packet coalescing for related actions
- Rate limiting to comply with server constraints
- Connection state awareness to prevent failed operations

### Error Recovery
- Automatic retry mechanisms for transient failures
- Graceful degradation when optional features are unavailable
- Comprehensive logging for debugging performance issues

## Troubleshooting Guide

Common issues and their solutions when working with Action Commands:

### Command Execution Failures
- **Symptom**: Commands return false without detailed error messages
- **Solution**: Enable debug logging and check command parameter validation
- **Prevention**: Validate prerequisites before command execution

### Timing Issues
- **Symptom**: Commands fail due to game state changes during execution
- **Solution**: Add appropriate delays between dependent commands
- **Prevention**: Use conditional checks and state verification

### Network Problems
- **Symptom**: Commands succeed locally but fail on server
- **Solution**: Implement retry logic and connection monitoring
- **Prevention**: Check network status before critical operations

### Resource Conflicts
- **Symptom**: Equipment or inventory operations fail unexpectedly
- **Solution**: Verify item availability and slot conflicts
- **Prevention**: Use atomic operations and transaction-like behavior

**Section sources**
- [ActionCommands.cs:200-400](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L200-L400)

## Conclusion

The Action Commands system provides a robust and flexible foundation for automating game operations in ClassicAssist. Through its modular architecture, comprehensive command set, and careful attention to performance and reliability, it enables players to create sophisticated automation patterns that enhance gameplay efficiency while maintaining the integrity of the gaming experience.

The system's design emphasizes maintainability, extensibility, and ease of use, making it accessible to both novice users creating simple macros and advanced developers building complex automation systems. With proper error handling, performance optimization, and integration with the broader macro ecosystem, Action Commands serve as a cornerstone of the ClassicAssist automation framework.

## Appendices

### Practical Automation Patterns

#### Inventory Management Pattern
```mermaid
flowchart TD
Start([Start Inventory Management]) --> CheckSpace["Check Available Space"]
CheckSpace --> HasSpace{"Sufficient Space?"}
HasSpace --> |No| Organize["Organize Inventory"]
HasSpace --> |Yes| ScanItems["Scan for Items"]
ScanItems --> FoundItems{"Items Found?"}
FoundItems --> |No| End([End])
FoundItems --> |Yes| SortItems["Sort by Priority"]
SortItems --> ProcessItems["Process Each Item"]
ProcessItems --> MoveItem["Move to Container"]
MoveItem --> NextItem{"More Items?"}
NextItem --> |Yes| ProcessItems
NextItem --> |No| End
Organize --> CheckSpace
```

**Diagram sources**
- [ActionCommands.cs:300-500](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs#L300-L500)

#### Equipment Switching Pattern
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Checking : "Monitor Conditions"
Checking --> NeedsSwitch{"Conditions Met?"}
NeedsSwitch --> |No| Idle
NeedsSwitch --> |Yes| Preparing["Prepare New Equipment"]
Preparing --> Equipping["Equip New Items"]
Equipping --> Verifying["Verify Equipment"]
Verifying --> Success{"Equipment Valid?"}
Success --> |Yes| Active["Active State"]
Success --> |No| Reverting["Revert Changes"]
Reverting --> Idle
Active --> Monitoring["Monitor Status"]
Monitoring --> Checking
```

**Diagram sources**
- [EquipLastWeapon.cs:100-200](file://ClassicAssist.Shared/Data/Hotkeys/Commands/EquipLastWeapon.cs#L100-L200)