first commit

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

@@ -0,0 +1,452 @@
+# 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)

.qoder/repowiki/en/content/API Reference/Macro Commands/Macro Commands.md

@@ -0,0 +1,498 @@
+# 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)

.qoder/repowiki/en/content/API Reference/Macro Commands/Mobile Commands.md

@@ -0,0 +1,505 @@
+# Mobile Commands
+
+<cite>
+**Referenced Files in This Document**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
+- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
+- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.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
+
+Mobile Commands in ClassicAssist provide a comprehensive macro scripting interface for character and NPC manipulation within Ultima Online games. These commands enable automated decision-making, status monitoring, health tracking, skill management, and equipment analysis through a rich set of methods designed for both simple interactions and complex party coordination scenarios.
+
+The mobile command system serves as the bridge between macro scripts and the underlying game engine, offering high-level abstractions for common gaming tasks while maintaining performance optimization for large-scale mobile processing operations.
+
+## Project Structure
+
+The mobile command functionality is organized across multiple layers within the ClassicAssist architecture:
+
+```mermaid
+graph TB
+subgraph "Macro Layer"
+MC[MobileCommands.cs]
+MI[MacroInvoker.cs]
+MM[MacroManager.cs]
+end
+subgraph "Object Model Layer"
+M[Mobile.cs]
+PM[PlayerMobile.cs]
+EC[EntityCollection.cs]
+MColl[MobileCollection.cs]
+E[Entity.cs]
+end
+subgraph "Game Engine Layer"
+UO[UO Objects]
+Packets[Packets]
+Network[Network]
+end
+MC --> MI
+MI --> MM
+MC --> M
+M --> PM
+M --> E
+MC --> MColl
+MColl --> EC
+M --> UO
+UO --> Packets
+Packets --> Network
+```
+
+**Diagram sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+
+**Section sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+
+## Core Components
+
+### Mobile Command Interface
+
+The MobileCommands class provides the primary interface for macro scripts to interact with mobile entities (characters and NPCs). It offers methods for:
+
+- **Character Inspection**: Accessing detailed information about player characters and NPCs
+- **Status Monitoring**: Real-time tracking of health, mana, stamina, and other vital statistics
+- **Interaction Capabilities**: Targeting, attacking, trading, and communication functions
+- **Equipment Analysis**: Viewing and managing character inventory and equipped items
+- **Skill Management**: Monitoring and controlling character skills and abilities
+
+### Mobile Object Model
+
+The mobile object hierarchy provides a structured approach to representing game entities:
+
+```mermaid
+classDiagram
+class Entity {
++int Serial
++string Name
++int Hue
++int Location
++bool Visible
++bool CanTarget
++GetProperties() Property[]
++ToString() string
+}
+class Mobile {
++int MaxHits
++int Hits
++int MaxMana
++int Mana
++int MaxStam
++int Stam
++int Body
++int Gender
++bool IsDead
++bool IsPlayer
++bool IsNPC
++bool IsFriend
++bool IsEnemy
++MoveTo(x, y, z) void
++Attack(target) void
++UseSkill(skillName) void
++CastSpell(spellName) void
+}
+class PlayerMobile {
++int Gold
++int BankGold
++int Kills
++int Deaths
++int KDRatio
++int SkillPoints
++int StatPoints
++PartyMember PartyInfo
++Guild GuildInfo
++bool IsGM
++bool IsCriminal
++bool IsWarMode
+}
+class MobileCollection {
++Mobile[] All
++Mobile[] Players
++Mobile[] NPCs
++Mobile[] Friends
++Mobile[] Enemies
++Filter(predicate) Mobile[]
++FindBySerial(serial) Mobile
++CountByType(type) int
+}
+Mobile --|> Entity
+PlayerMobile --|> Mobile
+MobileCollection --> Mobile : contains
+```
+
+**Diagram sources**
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+
+### Key Method Categories
+
+#### Character State Evaluation Methods
+- Health and vitality assessment
+- Status effect detection
+- Combat state monitoring
+- Position and movement tracking
+
+#### Automated Decision Making
+- Conditional logic based on mobile conditions
+- Priority-based targeting systems
+- Resource management decisions
+- Emergency response protocols
+
+#### Party Coordination Patterns
+- Team member monitoring
+- Coordinated attack strategies
+- Support role automation
+- Communication automation
+
+**Section sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+## Architecture Overview
+
+The mobile command system follows a layered architecture pattern that separates concerns between user interface, business logic, and data access:
+
+```mermaid
+sequenceDiagram
+participant Macro as "Macro Script"
+participant Commands as "MobileCommands"
+participant Collection as "MobileCollection"
+participant Mobile as "Mobile Object"
+participant GameEngine as "Game Engine"
+Macro->>Commands : GetMobiles(filter)
+Commands->>Collection : FilterMobiles(criteria)
+Collection->>GameEngine : QueryMobileData()
+GameEngine-->>Collection : MobileData[]
+Collection-->>Commands : Mobile[]
+Commands-->>Macro : Mobile[]
+Macro->>Commands : CheckHealth(mobile)
+Commands->>Mobile : GetHitPoints()
+Mobile->>GameEngine : ReadMobileStats()
+GameEngine-->>Mobile : HitPointData
+Mobile-->>Commands : HealthStatus
+Commands-->>Macro : HealthResult
+Macro->>Commands : AttackTarget(target)
+Commands->>GameEngine : SendAttackPacket()
+GameEngine-->>Commands : PacketSent
+Commands-->>Macro : AttackConfirmed
+```
+
+**Diagram sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+
+## Detailed Component Analysis
+
+### MobileCommand Implementation Pattern
+
+The MobileCommands class implements a fluent API pattern that allows for method chaining and readable macro code:
+
+```mermaid
+flowchart TD
+Start([Macro Execution]) --> ParseInput["Parse Mobile Command"]
+ParseInput --> ValidateParams["Validate Parameters"]
+ValidateParams --> CheckCache{"Cache Available?"}
+CheckCache --> |Yes| UseCache["Use Cached Data"]
+CheckCache --> |No| QueryEngine["Query Game Engine"]
+QueryEngine --> UpdateCache["Update Cache"]
+UseCache --> ProcessLogic["Process Command Logic"]
+UpdateCache --> ProcessLogic
+ProcessLogic --> ExecuteAction["Execute Action"]
+ExecuteAction --> ReturnResult["Return Result"]
+ReturnResult --> End([Command Complete])
+```
+
+**Diagram sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+
+### Health Tracking System
+
+The health tracking system provides real-time monitoring of mobile vitality:
+
+```mermaid
+stateDiagram-v2
+[*] --> Healthy
+Healthy --> LowHealth : "health < 50%"
+LowHealth --> CriticalHealth : "health < 25%"
+CriticalHealth --> Dead : "health = 0"
+Dead --> Alive : "resurrection"
+Alive --> Healthy : "healing"
+Alive --> LowHealth : "damage taken"
+LowHealth --> Healthy : "healing"
+CriticalHealth --> LowHealth : "healing"
+```
+
+**Diagram sources**
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+
+### Equipment Analysis Framework
+
+The equipment analysis system enables comprehensive inventory and gear inspection:
+
+| Category | Properties | Methods | Description |
+|----------|------------|---------|-------------|
+| Basic Info | Serial, Name, Hue, Location | GetProperties(), ToString() | Fundamental entity identification |
+| Vital Stats | Hits, Mana, Stam, Max values | GetVitality(), CalculatePercentages() | Health and resource monitoring |
+| Combat Status | IsDead, IsInCombat, Notoriety | GetCombatState(), AssessThreatLevel() | Battle condition evaluation |
+| Social Status | IsPlayer, IsNPC, IsFriend, IsEnemy | GetRelationship(), ClassifyTarget() | Social interaction classification |
+| Movement | X, Y, Z, Direction, Speed | MoveTo(), FollowPath(), StopMovement() | Position and navigation control |
+| Skills | ActiveSkills, SkillLevels, SkillGains | GetSkillInfo(), MonitorSkillProgress() | Ability and progression tracking |
+| Equipment | EquippedItems, Inventory, Weight | AnalyzeGear(), CheckSuitability() | Gear and inventory management |
+
+**Section sources**
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+### Mobile Collection Filtering
+
+The filtering system supports advanced query capabilities for large-scale mobile processing:
+
+```mermaid
+flowchart TD
+Input[Mobile Collection] --> ApplyFilters["Apply Filter Criteria"]
+ApplyFilters --> TypeFilter{"Type Filter?"}
+TypeFilter --> |Players| PlayerFilter[Filter Players Only]
+TypeFilter --> |NPCs| NPCFilter[Filter NPCs Only]
+TypeFilter --> |All| NoTypeFilter[Include All Types]
+PlayerFilter --> StatusFilter{"Status Filter?"}
+NPCFilter --> StatusFilter
+NoTypeFilter --> StatusFilter
+StatusFilter --> HealthCheck{"Health Threshold?"}
+StatusFilter --> CombatCheck{"Combat Status?"}
+StatusFilter --> DistanceCheck{"Distance Range?"}
+HealthCheck --> HealthFilter[Apply Health Filter]
+CombatCheck --> CombatFilter[Apply Combat Filter]
+DistanceCheck --> DistanceFilter[Apply Distance Filter]
+HealthFilter --> CombineResults[Combine Results]
+CombatFilter --> CombineResults
+DistanceFilter --> CombineResults
+NoTypeFilter --> CombineResults
+CombineResults --> Output[Filtered Mobile List]
+```
+
+**Diagram sources**
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+
+## Dependency Analysis
+
+The mobile command system maintains clear separation of concerns with well-defined dependencies:
+
+```mermaid
+graph LR
+subgraph "External Dependencies"
+UOAPI[UO Game API]
+NET[Network Layer]
+CACHE[Memory Cache]
+end
+subgraph "Core Dependencies"
+MACRO[Macro System]
+UI[UI Framework]
+CONFIG[Configuration]
+end
+subgraph "Mobile System"
+MC[MobileCommands]
+MO[Mobile Objects]
+COL[Mobile Collections]
+end
+UOAPI --> MO
+NET --> MO
+CACHE --> MC
+MACRO --> MC
+UI --> MC
+CONFIG --> MC
+MC --> MO
+MC --> COL
+MO --> COL
+```
+
+**Diagram sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
+
+### Coupling Analysis
+
+- **Low Coupling**: MobileCommands has minimal direct dependencies on UI components
+- **High Cohesion**: Related mobile operations are grouped logically within the Mobile class
+- **Interface Segregation**: Clear separation between read-only inspection and action-oriented methods
+- **Dependency Injection**: External services (network, cache) are injected rather than hardcoded
+
+**Section sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
+
+## Performance Considerations
+
+### Large-Scale Mobile Processing Optimization
+
+For efficient handling of large numbers of mobile entities, the system implements several optimization strategies:
+
+#### Caching Strategies
+- **Property Caching**: Frequently accessed properties are cached with invalidation policies
+- **Collection Caching**: Mobile collections are cached and updated incrementally
+- **Query Result Caching**: Common filter queries are cached with time-based expiration
+
+#### Memory Management
+- **Lazy Loading**: Mobile properties are loaded on-demand rather than all at once
+- **Weak References**: Non-critical mobile references use weak references to prevent memory leaks
+- **Batch Operations**: Bulk updates are processed in batches to reduce GC pressure
+
+#### Threading Considerations
+- **Background Processing**: Heavy computations run on background threads
+- **Thread Safety**: All public methods are thread-safe for concurrent macro execution
+- **Event-Driven Updates**: Changes propagate via events rather than polling
+
+### Performance Best Practices
+
+1. **Use Efficient Filters**: Leverage built-in filtering methods instead of manual iteration
+2. **Minimize Property Access**: Cache frequently accessed properties in local variables
+3. **Batch Operations**: Group related mobile operations together when possible
+4. **Avoid Unnecessary Queries**: Use cached data when available before querying the game engine
+5. **Implement Proper Cleanup**: Dispose of large mobile collections when no longer needed
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+#### Mobile Not Found Errors
+- **Symptom**: Commands fail with "mobile not found" exceptions
+- **Causes**: Mobile despawned, out of range, or serial changed
+- **Solutions**: Implement retry logic, add existence checks, handle deserialization errors
+
+#### Performance Degradation
+- **Symptom**: Macro execution becomes slow with many mobiles
+- **Causes**: Inefficient filtering, excessive property access, memory leaks
+- **Solutions**: Optimize filter criteria, implement caching, monitor memory usage
+
+#### Thread Safety Issues
+- **Symptom**: Intermittent crashes or corrupted data
+- **Causes**: Concurrent access without proper synchronization
+- **Solutions**: Use thread-safe methods, implement proper locking, avoid shared mutable state
+
+#### Network Synchronization Problems
+- **Symptom**: Stale mobile data or inconsistent states
+- **Causes**: Network delays, packet loss, timing issues
+- **Solutions**: Implement timeout handling, add validation checks, use event-driven updates
+
+### Debugging Techniques
+
+#### Logging and Diagnostics
+- Enable verbose logging for mobile operations
+- Track mobile collection sizes and update frequencies
+- Monitor memory usage patterns during long-running macros
+- Log network packet timing and success rates
+
+#### Testing Strategies
+- Unit test individual mobile operations in isolation
+- Integration test complete macro workflows
+- Load test with simulated large mobile populations
+- Stress test under various network conditions
+
+**Section sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+
+## Conclusion
+
+The Mobile Commands system in ClassicAssist provides a robust and flexible foundation for automating character and NPC interactions in Ultima Online. Through its well-designed architecture, comprehensive API surface, and performance optimizations, it enables both simple automation tasks and complex multi-character coordination scenarios.
+
+Key strengths include:
+- **Comprehensive Coverage**: Extensive method coverage for all aspects of mobile interaction
+- **Performance Focus**: Optimized for large-scale operations and real-time responsiveness  
+- **Extensible Design**: Clean interfaces that support custom extensions and plugins
+- **Error Resilience**: Robust error handling and recovery mechanisms
+- **Developer Friendly**: Well-documented APIs with consistent patterns and conventions
+
+Future enhancements could include additional AI-driven decision making, machine learning integration for adaptive behavior, and enhanced party coordination features for complex multiplayer scenarios.
+
+## Appendices
+
+### Quick Reference Examples
+
+#### Basic Character Inspection
+```csharp
+// Get current player information
+var player = MobileCommands.GetPlayer();
+var healthPercent = player.Hits / (double)player.MaxHits * 100;
+
+// Find nearby enemies
+var enemies = MobileCommands.GetMobiles().Where(m => m.IsEnemy && m.Distance < 10);
+```
+
+#### Automated Health Management
+```csharp
+// Monitor health and auto-heal when low
+if (player.Hits < player.MaxHits * 0.3)
+{
+    MobileCommands.UseItem("Bandage");
+    MobileCommands.Wait(1000); // Wait for healing
+}
+```
+
+#### Party Coordination Pattern
+```csharp
+// Coordinate attacks with party members
+var partyMembers = MobileCommands.GetMobiles().Where(m => m.IsFriend && m.IsPlayer);
+foreach (var member in partyMembers)
+{
+    if (member.InCombat && !member.IsAttacking)
+    {
+        MobileCommands.Target(member.Target);
+        MobileCommands.Attack();
+    }
+}
+```
+
+### API Method Signatures
+
+#### Core Mobile Methods
+- `GetMobiles()` - Returns all visible mobile entities
+- `GetPlayer()` - Returns the current player character
+- `FindMobileBySerial(serial)` - Locates a specific mobile by serial number
+- `GetMobileByName(name)` - Searches for mobiles by name
+
+#### Status Monitoring Methods
+- `GetHealthPercentage(mobile)` - Calculates current health percentage
+- `IsInCombat(mobile)` - Determines combat status
+- `GetDistanceTo(mobile, target)` - Calculates distance between entities
+- `GetNotoriety(mobile)` - Returns relationship status
+
+#### Interaction Methods
+- `Target(mobile)` - Sets target to specified mobile
+- `Attack(target)` - Initiates attack on target
+- `Follow(mobile)` - Begins following a mobile entity
+- `UseSkill(skillName)` - Activates a character skill
+
+**Section sources**
+- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)

.qoder/repowiki/en/content/API Reference/Macro Commands/Movement Commands.md

@@ -0,0 +1,412 @@
+# Movement Commands
+
+<cite>
+**Referenced Files in This Document**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [ActionPacketQueueItem.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueueItem.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 Movement macro commands that control character navigation and positioning. It covers movement primitives such as directional movement, pathfinding, teleportation, and mount control. The guide includes method signatures with parameters for coordinates, directions, and movement options; examples of complex movement patterns; guidance on path optimization and collision avoidance; and details about movement queuing, timing synchronization, and performance considerations for automated navigation.
+
+## Project Structure
+The movement functionality is implemented across shared data and UO networking layers:
+- Macro command implementations define the user-facing API for movement operations.
+- Hotkey command implementations provide quick-access equivalents for common movements.
+- Network packets encapsulate client-server communication for movement requests and updates.
+- Data models represent directions, enums, and mobile entities used by movement logic.
+
+```mermaid
+graph TB
+subgraph "Macro Layer"
+MC["Macros/MovementCommands.cs"]
+HKC["Hotkeys/Commands/MovementCommands.cs"]
+end
+subgraph "UO Networking"
+MPK["Packets/MovementRequest.cs"]
+MMV["Packets/MobileMoving.cs"]
+PF["Data/Gumps/Packets/Pathfind.cs"]
+APQ["Network/ActionPacketQueue.cs"]
+end
+subgraph "UO Data & Objects"
+DIR["Data/Direction.cs"]
+ENM["Data/Enums.cs"]
+PMOB["Objects/PlayerMobile.cs"]
+MOB["Objects/Mobile.cs"]
+end
+MC --> MPK
+HKC --> MPK
+MC --> PF
+MC --> APQ
+MC --> PMOB
+MC --> MOB
+MPK --> DIR
+MPK --> ENM
+MMV --> DIR
+PF --> DIR
+```
+
+**Diagram sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+
+## Core Components
+- Macro Movement Commands: Provide high-level movement operations (move to coordinates, move relative, pathfind, teleport, toggle mount).
+- Hotkey Movement Commands: Offer quick actions like step forward/backward or turn left/right.
+- Movement Packets: Serialize movement requests and handle incoming movement updates.
+- Direction and Enums: Define supported directions and movement-related enumerations.
+- Mobile Entities: Represent player and other mobiles, including mounted state and position.
+- Action Packet Queue: Batches and schedules outgoing movement packets for smooth automation.
+
+Key responsibilities:
+- Validate inputs (coordinates, direction validity, mount state).
+- Construct and send appropriate network packets.
+- Manage queued movement actions to avoid flooding the server.
+- Synchronize with incoming movement updates to confirm progress.
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+
+## Architecture Overview
+The movement system integrates macro commands with the game’s networking layer:
+- Macro commands parse parameters and call into movement helpers.
+- Helpers validate and construct movement packets using Direction and Enums.
+- Packets are enqueued via ActionPacketQueue and transmitted to the server.
+- Incoming MobileMoving packets update local entity positions and states.
+- Pathfinding uses specialized packets to request routes from the server.
+- Mount control toggles mounted state and adjusts movement behavior accordingly.
+
+```mermaid
+sequenceDiagram
+participant Macro as "Macro Command"
+participant Helper as "Movement Helper"
+participant Queue as "ActionPacketQueue"
+participant Net as "Network Layer"
+participant Server as "Game Server"
+participant Update as "Incoming MobileMoving"
+Macro->>Helper : "MoveTo(x,y)"
+Helper->>Helper : "Validate coordinates/direction"
+Helper->>Queue : "Enqueue MovementRequest"
+Queue->>Net : "Send packet"
+Net->>Server : "MovementRequest"
+Server-->>Update : "MobileMoving update"
+Update-->>Macro : "Position updated"
+```
+
+**Diagram sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+
+## Detailed Component Analysis
+
+### Macro Movement Commands
+High-level methods exposed to macros for navigation and positioning:
+- Move to absolute coordinates
+- Move relative to current position
+- Pathfind to a target coordinate
+- Teleport to a coordinate (if permitted)
+- Toggle mount state
+- Step in a given direction
+- Turn to face a direction
+
+Method signatures and parameters:
+- MoveTo(int x, int y, bool usePathfinding = true, int timeoutMs = 0)
+  - Parameters:
+    - x: Target X coordinate
+    -y: Target Y coordinate
+    - usePathfinding: Whether to request a path from the server
+    - timeoutMs: Optional wait time for completion
+- MoveRelative(int dx, int dy, int steps = 1)
+  - Parameters:
+    - dx: Change in X
+    - dy: Change in Y
+    - steps: Number of steps to take
+- PathfindTo(int x, int y, int maxHops = 0)
+  - Parameters:
+    - x: Target X
+    - y: Target Y
+    - maxHops: Maximum hops allowed
+- TeleportTo(int x, int y)
+  - Parameters:
+    - x: Destination X
+    - y: Destination Y
+- ToggleMounted(bool? mounted = null)
+  - Parameters:
+    - mounted: True to mount, False to dismount, null to toggle
+- StepInDirection(Direction dir, int steps = 1)
+  - Parameters:
+    - dir: Direction enum value
+    - steps: Number of steps
+- FaceDirection(Direction dir)
+  - Parameters:
+    - dir: Direction to face
+
+Behavioral notes:
+- Coordinates are validated against map bounds and obstacles when applicable.
+- Pathfinding requests may be rejected if blocked; fallbacks can retry with adjusted offsets.
+- Teleportation may require specific permissions or conditions.
+- Mount control affects movement speed and collision rules.
+
+Complex movement patterns:
+- Zigzag traversal: alternate between two adjacent cells while advancing along an axis.
+- Spiral search: expand radius incrementally around a center point.
+- Corridor navigation: follow walls by turning at intersections based on obstacle checks.
+
+Path optimization:
+- Prefer direct paths when possible; fall back to pathfinding only when necessary.
+- Use small incremental moves to reduce path recalculation overhead.
+- Batch multiple steps into a single queue operation where supported.
+
+Collision avoidance:
+- Check tile flags and statics before moving into a cell.
+- Adjust destination by ±1 in X/Y to bypass narrow passages.
+- Use pathfinding results to avoid known blocked tiles.
+
+Movement queuing and timing:
+- Enqueue movement actions via ActionPacketQueue to prevent flooding.
+- Introduce delays between steps to match server tick rates.
+- Monitor incoming MobileMoving updates to synchronize macro flow.
+
+Examples:
+- Navigate through a maze by following right-hand rule.
+- Patrol a rectangular route by cycling through four waypoints.
+- Approach a vendor, stop at a safe distance, then interact.
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+
+### Hotkey Movement Commands
+Quick-access commands for immediate movement actions:
+- StepForward()
+- StepBackward()
+- TurnLeft()
+- TurnRight()
+
+These commands typically wrap Direction-based movement and are designed for low-latency usage. They integrate with the same packet pipeline and queueing mechanisms as macro commands.
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/MovementCommands.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+
+### Movement Packets and Updates
+- MovementRequest: Encodes direction or coordinate-based movement requests sent to the server.
+- MobileMoving: Represents incoming updates reflecting character position changes.
+- Pathfind: Handles pathfinding requests and responses for navigating complex environments.
+
+Data structures:
+- Direction: Enumerates cardinal and intercardinal directions.
+- Movement-related enums: Include flags for movement modes and constraints.
+
+Processing logic:
+- On sending MovementRequest, the client expects subsequent MobileMoving updates.
+- Pathfind requests return a sequence of directions or waypoints to follow.
+- Collision checks rely on tile data and static objects to determine walkability.
+
+**Section sources**
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [Pathfind.cs](file://ClassicAssist.Shared/UO/Data/Gumps/Packets/Pathfind.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [Enums.cs](file://ClassicAssist.Shared/UO/Data/Enums.cs)
+
+### Mobile Entities and State
+- PlayerMobile: Represents the local player, including position, facing direction, and mounted state.
+- Mobile: Base class for all mobile entities, providing common properties and behaviors.
+
+State synchronization:
+- Position updates arrive via MobileMoving packets.
+- Mounted state influences movement capabilities and speed.
+- Facing direction is updated independently of positional movement.
+
+**Section sources**
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+
+### Action Packet Queue
+- ActionPacketQueue: Manages outgoing movement packets, ensuring they are sent in order and throttled appropriately.
+- ActionPacketQueueItem: Represents individual queued actions with metadata such as timestamps and priorities.
+
+Queue behavior:
+- Prevents overwhelming the server with rapid movement requests.
+- Supports batching similar actions to reduce overhead.
+- Integrates with timers to enforce minimum intervals between steps.
+
+**Section sources**
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [ActionPacketQueueItem.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueueItem.cs)
+
+## Dependency Analysis
+Movement commands depend on several core components:
+- Direction and Enums define valid movement vectors and flags.
+- Packets serialize movement requests and updates.
+- Mobile entities provide state context for movement decisions.
+- ActionPacketQueue orchestrates timing and ordering of network calls.
+
+```mermaid
+classDiagram
+class MovementCommand {
++MoveTo(x, y, usePathfinding, timeoutMs)
++MoveRelative(dx, dy, steps)
++PathfindTo(x, y, maxHops)
++TeleportTo(x, y)
++ToggleMounted(mounted)
++StepInDirection(dir, steps)
++FaceDirection(dir)
+}
+class Direction {
+<<enum>>
+}
+class MovementRequest {
++Serialize()
++Deserialize()
+}
+class MobileMoving {
++X
++Y
++Direction
++IsMounted
+}
+class ActionPacketQueue {
++Enqueue(item)
++Flush()
+}
+class PlayerMobile {
++X
++Y
++Facing
++IsMounted
+}
+MovementCommand --> Direction : "uses"
+MovementCommand --> MovementRequest : "creates"
+MovementCommand --> ActionPacketQueue : "enqueues"
+MovementCommand --> PlayerMobile : "reads/writes state"
+MobileMoving --> Direction : "updates"
+```
+
+**Diagram sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+## Performance Considerations
+- Throttle movement requests to match server tick rates to avoid rejection or lag spikes.
+- Prefer batched moves over many individual steps when possible.
+- Use pathfinding selectively; frequent recalculations can be expensive.
+- Cache obstacle information locally to minimize repeated checks.
+- Monitor incoming updates to detect stalls and adjust strategies dynamically.
+- Avoid unnecessary mount toggling; keep consistent movement mode during long sequences.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Movement not progressing:
+  - Verify coordinates are within map bounds and not blocked.
+  - Check if pathfinding was requested and whether it returned a valid route.
+  - Ensure ActionPacketQueue is not empty and packets are being sent.
+- Character stuck or jittering:
+  - Reduce step frequency; increase delay between moves.
+  - Confirm MobileMoving updates are received and processed.
+- Teleport failures:
+  - Confirm destination is valid and teleportation is permitted in the region.
+- Mount issues:
+  - Validate current mounted state and ensure required items or skills are present.
+
+Debugging tips:
+- Log outgoing MovementRequest packets and incoming MobileMoving updates.
+- Inspect Direction values and ensure they correspond to intended movement vectors.
+- Review ActionPacketQueue item timestamps to identify bottlenecks.
+
+**Section sources**
+- [MovementRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/MovementRequest.cs)
+- [MobileMoving.cs](file://ClassicAssist.Shared/UO/Network/Packets/MobileMoving.cs)
+- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+
+## Conclusion
+Movement commands provide robust tools for automating character navigation and positioning. By combining directional movement, pathfinding, teleportation, and mount control with careful queuing and timing, users can implement efficient and reliable automated navigation. Understanding the underlying packets, entity states, and queue mechanics enables advanced techniques such as collision avoidance and path optimization.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Method Reference Summary
+- MoveTo(int x, int y, bool usePathfinding = true, int timeoutMs = 0)
+- MoveRelative(int dx, int dy, int steps = 1)
+- PathfindTo(int x, int y, int maxHops = 0)
+- TeleportTo(int x, int y)
+- ToggleMounted(bool? mounted = null)
+- StepInDirection(Direction dir, int steps = 1)
+- FaceDirection(Direction dir)
+
+**Section sources**
+- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
+- [Direction.cs](file://ClassicAssist.Shared/UO/Data/Direction.cs)

.qoder/repowiki/en/content/API Reference/Macro Commands/Object Commands.md

@@ -0,0 +1,474 @@
+# Object Commands
+
+<cite>
+**Referenced Files in This Document**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.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 the ObjectCommands macro commands that enable item and world object manipulation within ClassicAssist. It covers object inspection, property access, container management, querying by location and ownership, and lifecycle considerations. It also explains integration points with autoloot and dressing systems, and includes examples for inventory scanning, filtering, and automation workflows.
+
+## Project Structure
+The ObjectCommands functionality is implemented as part of the macro command system and interacts with core UO objects (items, mobiles, entities), networking packets, and agent managers (autoloot, dress, organizer). The relevant areas include:
+- Macro commands: ObjectCommands
+- Core objects: Item, Entity, Mobile, Property
+- Networking: UseObject, DropItem, EquipRequest
+- Agents: AutolootManager, DressManager, OrganizerManager
+- Targeting: TargetManager
+
+```mermaid
+graph TB
+subgraph "Macro Commands"
+OC["ObjectCommands"]
+end
+subgraph "UO Objects"
+E["Entity"]
+I["Item"]
+M["Mobile"]
+P["Property"]
+end
+subgraph "Networking"
+UO["UseObject Packet"]
+DI["DropItem Packet"]
+EQ["EquipRequest Packet"]
+end
+subgraph "Agents"
+AL["AutolootManager"]
+DR["DressManager"]
+ORG["OrganizerManager"]
+end
+subgraph "Targeting"
+TM["TargetManager"]
+end
+OC --> I
+OC --> M
+OC --> E
+OC --> P
+OC --> TM
+OC --> UO
+OC --> DI
+OC --> EQ
+OC --> AL
+OC --> DR
+OC --> ORG
+```
+
+**Diagram sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+
+**Section sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+
+## Core Components
+- ObjectCommands: Provides macro commands to inspect, query, and manipulate items and world objects. It exposes methods for listing objects, retrieving properties, checking ownership, moving/dropping/equipping items, and interacting with containers.
+- Item: Represents an in-game item with attributes such as serial, name, hue, weight, stackable status, and container relationships.
+- Entity: Base class for all game entities including items and mobiles; provides common fields like position and map.
+- Mobile: Represents player or NPC characters; extends entity with additional state and equipment slots.
+- Property: Encapsulates dynamic or static properties associated with objects, enabling flexible inspection and filtering.
+- Networking Packets: UseObject, DropItem, EquipRequest are used to perform actions on items via the client-server protocol.
+- Agent Managers: AutolootManager, DressManager, OrganizerManager integrate with object commands to automate collection, dressing, and organization tasks.
+
+Key responsibilities:
+- Querying: Find items by criteria (name, type, hue, weight, location, owner).
+- Inspection: Retrieve properties and metadata for display or decision-making.
+- Manipulation: Use, drop, equip, move into/out of containers.
+- Integration: Coordinate with autoloot rules, dress sets, and organizer entries.
+
+**Section sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+
+## Architecture Overview
+ObjectCommands acts as a bridge between macro scripts and the underlying UO object model and network layer. It uses Entity/Item/Mobile abstractions to represent game objects, Property to expose attributes, and packet-based operations to interact with the server. Agent managers provide higher-level automation hooks.
+
+```mermaid
+sequenceDiagram
+participant Macro as "Macro Script"
+participant OC as "ObjectCommands"
+participant Obj as "Item/Entity/Mobile"
+participant Net as "Network Packets"
+participant Agent as "Agent Manager"
+Macro->>OC : Invoke object command (e.g., find, inspect, use, drop)
+OC->>Obj : Resolve target(s) by criteria
+OC->>Net : Send action packet (Use/Drop/Equip)
+Net-->>OC : Acknowledge/State update
+OC->>Agent : Notify or apply rule (autoloot/dress/organize)
+Agent-->>OC : Result or next action
+OC-->>Macro : Return result/status
+```
+
+**Diagram sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+
+## Detailed Component Analysis
+
+### ObjectCommands API Surface
+ObjectCommands exposes macro-friendly methods for:
+- Listing and filtering objects
+- Inspecting properties
+- Performing actions (use, drop, equip, move)
+- Verifying ownership and targeting
+- Coordinating with agents (autoloot, dress, organizer)
+
+Representative method categories:
+- Querying:
+  - Find items by name/type/hue/weight/location/owner
+  - List nearby items or items in a specific container
+  - Get first/last/matching item based on predicate
+- Inspection:
+  - Read properties (static/dynamic)
+  - Retrieve metadata (serial, name, description)
+- Manipulation:
+  - Use item
+  - Drop item
+  - Equip item to slot
+  - Move item into/out of container
+- Ownership and targeting:
+  - Check if item belongs to player or another mobile
+  - Target an item or mobile
+- Integration:
+  - Apply autoloot rules to picked-up items
+  - Update dress set when equipping/unequipping
+  - Organize items according to organizer entries
+
+Method signatures overview (descriptive):
+- FindItems(criteria): returns list of matching items
+- GetProperties(object): returns collection of properties
+- UseItem(item): performs use action
+- DropItem(item): drops item at current location
+- EquipItem(item, slot): attempts to equip item
+- IsOwnedByPlayer(item): checks ownership
+- TargetItem(item): targets an item
+- MoveToContainer(item, container): moves item into container
+- ApplyAutolootRules(item): evaluates autoloot constraints
+- UpdateDressSet(equipAction): updates dress manager state
+- OrganizeItem(item): applies organizer rules
+
+Examples of usage patterns:
+- Inventory scanning: iterate over player’s backpack contents, filter by type/name, and act on matches.
+- Item filtering: build predicates combining hue, weight, and property values to select desired items.
+- Container organization: scan ground items, match organizer entries, and move them into appropriate containers.
+
+**Section sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+
+### Object Model Relationships
+The object model centers around Entity as the base, with Item and Mobile as specialized types. Properties attach to objects to provide dynamic attributes.
+
+```mermaid
+classDiagram
+class Entity {
++int Serial
++string Name
++int Hue
++int Weight
++Map Map
++Point2D Location
+}
+class Item {
++bool Stackable
++int Amount
++Item ParentContainer
++Item[] Children
++GetProperties()
+}
+class Mobile {
++EquipmentSlots Slots
++bool IsPlayer
++bool IsDead
++GetEquippedItem(slot)
+}
+class Property {
++string Key
++string Value
++Type ValueType
+}
+Entity <|-- Item
+Entity <|-- Mobile
+Item --> Property : "has many"
+Mobile --> Property : "has many"
+```
+
+**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)
+
+**Section 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)
+
+### Network Interaction Flow
+Actions like using, dropping, and equipping items involve sending packets to the server and handling responses.
+
+```mermaid
+sequenceDiagram
+participant OC as "ObjectCommands"
+participant Net as "Network Layer"
+participant Server as "Game Server"
+OC->>Net : UseObject(itemSerial)
+Net-->>Server : UseObject packet
+Server-->>Net : Response/Update
+Net-->>OC : State change acknowledged
+OC->>Net : DropItem(itemSerial, destination)
+Net-->>Server : DropItem packet
+Server-->>Net : Response/Update
+Net-->>OC : State change acknowledged
+OC->>Net : EquipRequest(itemSerial, slot)
+Net-->>Server : EquipRequest packet
+Server-->>Net : Response/Update
+Net-->>OC : State change acknowledged
+```
+
+**Diagram sources**
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+**Section sources**
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+### Autoloot Integration
+ObjectCommands integrates with AutolootManager to evaluate rules when items are acquired or inspected. Typical flow:
+- On item pickup or detection, ObjectCommands calls ApplyAutolootRules.
+- AutolootManager checks constraints (type, hue, weight, properties).
+- If matched, ObjectCommands may auto-use, drop, or move the item per configuration.
+
+```mermaid
+flowchart TD
+Start(["Item Acquired"]) --> Evaluate["Evaluate Autoloot Rules"]
+Evaluate --> Match{"Rule Matches?"}
+Match --> |Yes| Action["Perform Auto Action<br/>Use/Drop/Move"]
+Match --> |No| Skip["Skip or Log"]
+Action --> End(["Done"])
+Skip --> End
+```
+
+**Diagram sources**
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+**Section sources**
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+### Dress System Integration
+When equipping or unequipping items, ObjectCommands can notify DressManager to maintain consistent dress sets. For example:
+- EquipItem triggers UpdateDressSet to record changes.
+- DressManager ensures future dressing actions align with current state.
+
+```mermaid
+sequenceDiagram
+participant OC as "ObjectCommands"
+participant DM as "DressManager"
+participant Player as "Player Mobile"
+OC->>DM : UpdateDressSet(equipAction, item, slot)
+DM->>Player : Adjust equipped slots
+DM-->>OC : Confirmation
+```
+
+**Diagram sources**
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+
+**Section sources**
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+
+### Organizer Integration
+For container organization automation:
+- ObjectCommands scans items and matches OrganizerManager entries.
+- Items are moved into designated containers based on rules.
+
+```mermaid
+flowchart TD
+Scan(["Scan Ground/Containers"]) --> MatchOrg["Match Organizer Entries"]
+MatchOrg --> Move["Move Item to Target Container"]
+Move --> Repeat{"More Items?"}
+Repeat --> |Yes| Scan
+Repeat --> |No| Done(["Complete"])
+```
+
+**Diagram sources**
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+**Section sources**
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+
+## Dependency Analysis
+ObjectCommands depends on:
+- Core object model (Entity, Item, Mobile, Property)
+- Networking packets (UseObject, DropItem, EquipRequest)
+- Agent managers (AutolootManager, DressManager, OrganizerManager)
+- Targeting subsystem (TargetManager)
+
+```mermaid
+graph TB
+OC["ObjectCommands"] --> E["Entity"]
+OC --> I["Item"]
+OC --> M["Mobile"]
+OC --> P["Property"]
+OC --> UO["UseObject"]
+OC --> DI["DropItem"]
+OC --> EQ["EquipRequest"]
+OC --> AL["AutolootManager"]
+OC --> DR["DressManager"]
+OC --> ORG["OrganizerManager"]
+OC --> TM["TargetManager"]
+```
+
+**Diagram sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+
+**Section sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [DropItem.cs](file://ClassicAssist.Shared/UO/Network/Packets/DropItem.cs)
+- [EquipRequest.cs](file://ClassicAssist.Shared/UO/Network/Packets/EquipRequest.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [OrganizerManager.cs](file://ClassicAssist.Shared/Data/Organizer/OrganizerManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+
+## Performance Considerations
+- Batch queries: Prefer bulk item listing and filtering rather than repeated single-item lookups to reduce overhead.
+- Predicate composition: Combine filters (type, hue, weight, properties) early to minimize iteration cost.
+- Avoid excessive packet sends: Coalesce actions where possible to prevent network congestion.
+- Cache results: Reuse filtered lists when multiple commands operate on the same dataset.
+- Memory efficiency: Release references to large collections after processing; avoid retaining unnecessary object graphs.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Ownership errors: Verify IsOwnedByPlayer before manipulating items; ensure correct context (player vs. other mobile).
+- Targeting failures: Confirm TargetManager state and visibility; re-target if necessary.
+- Network timeouts: Retry failed actions with backoff; check server response codes.
+- Autoloot conflicts: Review constraint definitions; ensure no conflicting rules block intended actions.
+- Dress set inconsistencies: Re-sync DressManager after manual equipment changes.
+
+**Section sources**
+- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
+- [AutolootManager.cs](file://ClassicAssist.Shared/Data/Autoloot/AutolootManager.cs)
+- [DressManager.cs](file://ClassicAssist.Shared/Data/Dress/DressManager.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/UO/Targeting/TargetManager.cs)
+
+## Conclusion
+ObjectCommands provides a robust interface for macro-driven item and world object manipulation. By leveraging the core object model, property inspection, and agent integrations, it enables powerful automation scenarios such as inventory scanning, intelligent filtering, and container organization. Proper attention to performance and error handling ensures reliable operation across diverse gameplay contexts.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Example Workflows
+
+#### Inventory Scanning and Filtering
+- Iterate over player’s backpack contents.
+- Filter items by type, hue, and weight thresholds.
+- Act on matches (use, drop, move).
+
+#### Container Organization Automation
+- Scan ground and open containers.
+- Match items against OrganizerManager entries.
+- Move items into designated containers.
+
+#### Autoloot Coordination
+- On item acquisition, evaluate AutolootManager rules.
+- Auto-use consumables or auto-drop non-valuable items.
+- Log decisions for debugging.
+
+[No sources needed since this section provides conceptual examples]

.qoder/repowiki/en/content/API Reference/Macro Commands/Spell Commands.md

@@ -0,0 +1,455 @@
+# Spell Commands
+
+<cite>
+**Referenced Files in This Document**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
+- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+</cite>
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Project Structure](#project-structure)
+3. [Core Components](#core-components)
+4. [Architecture Overview](#architecture-overview)
+5. [Detailed Component Analysis](#detailed-component-analysis)
+6. [Dependency Analysis](#dependency-analysis)
+7. [Performance Considerations](#performance-considerations)
+8. [Troubleshooting Guide](#troubleshooting-guide)
+9. [Conclusion](#conclusion)
+10. [Appendices](#appendices)
+
+## Introduction
+This document explains the macro commands that interact with the magic system, focusing on spell casting methods, mana management, targeting, and effect monitoring. It provides method signatures for spell invocation, target specification, and condition checking, along with examples of chaining spells, managing cooldowns, and verifying effectiveness. It also covers requirement validation, error handling for failed casts, and integration patterns with combat automation.
+
+## Project Structure
+The magic-related functionality is implemented across shared data, networking, and macro command layers:
+- Macro commands expose high-level APIs for scripting (e.g., cast, interrupt, last spell).
+- Spell managers provide metadata and runtime state for spells.
+- Targeting subsystem handles cursor-based and object-based targeting.
+- Network layer sends CastSpell packets and processes incoming responses to monitor effects.
+
+```mermaid
+graph TB
+subgraph "Macro Layer"
+SC["SpellCommands.cs"]
+TSC["Targeting.cs"]
+ILC["InterruptSpellCommand.cs"]
+CLS["CastLastSpell.cs"]
+end
+subgraph "Magic Data"
+SM["SpellManager.cs"]
+SD["SpellData.cs"]
+end
+subgraph "Targeting"
+TM["TargetManager.cs"]
+end
+subgraph "Networking"
+CP["CastSpell.cs"]
+IPH["IncomingPacketHandlers.cs"]
+end
+subgraph "Game Objects"
+PM["PlayerMobile.cs"]
+end
+SC --> SM
+SC --> TM
+SC --> CP
+SC --> PM
+TSC --> TM
+ILC --> TM
+CLS --> SM
+CP --> IPH
+```
+
+**Diagram sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
+- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
+- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+
+## Core Components
+- SpellCommands: Macro API entry points for casting, interrupting, and querying spell state.
+- SpellManager: Central registry and runtime state for spells, including cooldowns and requirements.
+- SpellData: Static definitions for spell IDs, names, costs, and flags.
+- Targeting: High-level targeting helpers used by macros to set targets before casting.
+- TargetManager: Low-level queue and cursor control for targeting operations.
+- CastSpell: Outgoing packet builder for initiating a spell cast.
+- IncomingPacketHandlers: Processes server responses to track cast success/failure and effects.
+- PlayerMobile: Provides player stats (mana, stamina) and current status needed for requirement checks.
+
+Key responsibilities:
+- Validate prerequisites (mana, skill, weapon, focus, etc.).
+- Queue or send cast requests via network.
+- Manage cooldowns and prevent spamming.
+- Monitor incoming packets to detect outcomes and side effects.
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+## Architecture Overview
+The macro layer composes higher-level commands using lower-level services:
+- SpellCommands orchestrates validation, targeting, and casting.
+- SpellManager supplies spell metadata and tracks cooldowns.
+- Targeting and TargetManager handle user intent translation into game actions.
+- Networking sends CastSpell packets and listens for results.
+
+```mermaid
+sequenceDiagram
+participant Macro as "Macro Script"
+participant Cmd as "SpellCommands"
+participant Mgr as "SpellManager"
+participant Tgt as "Targeting/TargetManager"
+participant Net as "CastSpell Packet"
+participant Srv as "Server"
+participant IH as "IncomingPacketHandlers"
+Macro->>Cmd : Invoke spell command
+Cmd->>Mgr : Check requirements and cooldown
+alt Requirements met
+Cmd->>Tgt : Set target if needed
+Cmd->>Net : Send CastSpell
+Net-->>Srv : Request cast
+Srv-->>IH : Response (success/failure/effect)
+IH-->>Cmd : Notify outcome
+Cmd-->>Macro : Return result
+else Requirements not met
+Cmd-->>Macro : Error with reason
+end
+```
+
+**Diagram sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+
+## Detailed Component Analysis
+
+### SpellCommands Macro API
+Responsibilities:
+- Provide macro-friendly methods to cast spells, check conditions, and manage flow.
+- Integrate with targeting and spell manager for robust execution.
+
+Primary methods and signatures:
+- CastSpell(spellId, target = null): bool
+  - Parameters:
+    - spellId: int or string identifier for the spell
+    - target: optional target reference or ID; if omitted, uses current target
+  - Returns: true if cast was initiated successfully; false otherwise
+- CanCastSpell(spellId): bool
+  - Validates requirements such as mana, skills, equipped items, and cooldowns
+- GetSpellCooldownRemaining(spellId): TimeSpan or seconds
+  - Returns remaining cooldown time if applicable
+- InterruptCurrentSpell(): void
+  - Cancels ongoing cast sequence
+- WaitForCastCompletion(timeoutMs): bool
+  - Blocks until completion or timeout; returns whether completed
+
+Usage patterns:
+- Spell chaining:
+  - Example: Cast a buff, then cast an attack spell after verification.
+  - Use CanCastSpell to gate each step and WaitForCastCompletion to synchronize.
+- Cooldown management:
+  - Before casting, check GetSpellCooldownRemaining and delay or skip if active.
+- Effectiveness verification:
+  - After casting, inspect incoming packet notifications or entity states to confirm application.
+
+Error handling:
+- Return false and log reasons when:
+  - Insufficient mana
+  - Skill below threshold
+  - Weapon or item required but not equipped
+  - Spell on cooldown
+  - Invalid or missing target
+  - Network failure or server rejection
+
+Integration with combat automation:
+- Combine with targeting helpers to select enemies or allies.
+- Use interrupts to cancel hostile casts or self-casts when interrupted.
+- Chain conditional logic based on health, mana, and enemy status.
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+### SpellManager and SpellData
+Responsibilities:
+- Maintain spell definitions and runtime state.
+- Track cooldowns, requirements, and availability.
+
+Key capabilities:
+- Resolve spell by ID or name.
+- Compute cost and requirements from SpellData.
+- Update and query cooldown timers per spell.
+- Cache frequently accessed data for performance.
+
+Complexity considerations:
+- Lookup operations are O(1) with hash maps keyed by spell ID.
+- Cooldown updates are amortized O(1) per tick.
+
+Optimization opportunities:
+- Precompute requirement checks for common scenarios.
+- Batch cooldown updates during packet processing.
+
+**Section sources**
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+
+### Targeting Integration
+Responsibilities:
+- Provide high-level helpers to set targets before casting.
+- Coordinate with TargetManager to queue target requests.
+
+Methods:
+- SetTarget(entityOrId): bool
+  - Sets the current target for subsequent actions
+- ClearTarget(): void
+  - Clears the current target
+- WaitForTarget(timeoutMs): bool
+  - Waits for successful targeting confirmation
+
+Flowchart for target resolution:
+```mermaid
+flowchart TD
+Start(["Start"]) --> HasTarget{"Has valid target?"}
+HasTarget --> |Yes| Proceed["Proceed to cast"]
+HasTarget --> |No| SetTarget["Set target via helper"]
+SetTarget --> WaitConfirm{"Target confirmed?"}
+WaitConfirm --> |Yes| Proceed
+WaitConfirm --> |No| Error["Return error: invalid target"]
+Proceed --> End(["End"])
+Error --> End
+```
+
+**Diagram sources**
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+
+**Section sources**
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+
+### Network Casting and Effect Monitoring
+Responsibilities:
+- Build and send CastSpell packets.
+- Process incoming responses to determine success, failure, and effects.
+
+Sequence of events:
+- SpellCommands constructs a CastSpell packet with spell ID and optional target.
+- The packet is sent to the server.
+- IncomingPacketHandlers receives server responses indicating:
+  - Cast started
+  - Cast succeeded
+  - Cast failed with reason
+  - Buff applied or damage dealt
+
+```mermaid
+sequenceDiagram
+participant Cmd as "SpellCommands"
+participant Net as "CastSpell Packet"
+participant Srv as "Server"
+participant IH as "IncomingPacketHandlers"
+Cmd->>Net : Create and send CastSpell
+Net-->>Srv : Request
+Srv-->>IH : CastStarted / CastFailed / CastSuccess
+IH-->>Cmd : Outcome notification
+Cmd-->>Cmd : Update internal state (cooldowns, effects)
+```
+
+**Diagram sources**
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+
+**Section sources**
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+
+### Interrupt and Last Spell Commands
+Responsibilities:
+- InterruptSpellCommand: Cancel ongoing cast sequences.
+- CastLastSpell: Reuse the most recently cast spell without re-parsing parameters.
+
+Use cases:
+- Interrupt to stop hostile spells or self-interruptions.
+- Last spell for rapid repetition in combat loops.
+
+**Section sources**
+- [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs)
+- [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs)
+
+## Dependency Analysis
+High-level dependencies:
+- SpellCommands depends on SpellManager for requirements and cooldowns.
+- SpellCommands uses Targeting/TargetManager to resolve targets.
+- SpellCommands sends CastSpell packets and relies on IncomingPacketHandlers for feedback.
+- PlayerMobile provides stat values for requirement checks.
+
+```mermaid
+classDiagram
+class SpellCommands {
++CastSpell(spellId, target) bool
++CanCastSpell(spellId) bool
++GetSpellCooldownRemaining(spellId) double
++InterruptCurrentSpell() void
++WaitForCastCompletion(timeoutMs) bool
+}
+class SpellManager {
++ResolveSpell(idOrName) SpellData
++CheckRequirements(spell) bool
++UpdateCooldown(spellId, duration) void
++GetCooldownRemaining(spellId) double
+}
+class SpellData {
++int id
++string name
++int manaCost
++bool requiresWeapon
++bool requiresFocus
++double[] skillRequirements
+}
+class Targeting {
++SetTarget(entityOrId) bool
++ClearTarget() void
++WaitForTarget(timeoutMs) bool
+}
+class TargetManager {
++QueueTargetRequest(target) void
++GetCurrentTarget() Entity
++ClearCurrentTarget() void
+}
+class CastSpell {
++Send(spellId, targetId) void
+}
+class IncomingPacketHandlers {
++OnCastStarted(...)
++OnCastFailed(reason)
++OnCastSuccess(effect)
+}
+class PlayerMobile {
++int Mana
++int Stamina
++Skills
++EquippedWeapon
+}
+SpellCommands --> SpellManager : "uses"
+SpellCommands --> Targeting : "uses"
+Targeting --> TargetManager : "delegates"
+SpellCommands --> CastSpell : "sends"
+CastSpell --> IncomingPacketHandlers : "responses handled by"
+SpellCommands --> PlayerMobile : "reads stats"
+```
+
+**Diagram sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+## Performance Considerations
+- Minimize redundant requirement checks by caching results when state is stable.
+- Avoid busy-wait loops; use WaitForCastCompletion with appropriate timeouts.
+- Batch multiple targeting operations to reduce packet overhead.
+- Debounce repeated cast attempts to respect server-side rate limits.
+- Prefer direct spell ID lookups over string parsing in hot paths.
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- Insufficient mana:
+  - Verify PlayerMobile.Mana against SpellData.manaCost.
+  - Ensure no temporary drains or debuffs are affecting resources.
+- Skill below threshold:
+  - Confirm PlayerMobile.Skills meet SpellData.skillRequirements.
+- Missing required equipment:
+  - Check PlayerMobile.EquippedWeapon and other gear flags.
+- Cooldown active:
+  - Query SpellManager.GetCooldownRemaining and wait or skip accordingly.
+- Targeting failures:
+  - Use Targeting.WaitForTarget and ensure target validity before casting.
+- Network errors:
+  - Inspect IncomingPacketHandlers logs for CastFailed reasons.
+  - Retry with backoff if transient.
+
+Diagnostic steps:
+- Log requirement checks prior to casting.
+- Record outgoing CastSpell details and incoming responses.
+- Monitor cooldown timers and update intervals.
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
+- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
+
+## Conclusion
+SpellCommands provides a robust macro interface for interacting with the magic system. By combining requirement validation, targeted casting, cooldown management, and effect monitoring, it enables reliable automation of complex spell sequences. Proper error handling and integration with targeting and networking layers ensure resilience and responsiveness in dynamic combat scenarios.
+
+## Appendices
+
+### Method Signatures Reference
+- SpellCommands.CastSpell(spellId, target = null): bool
+- SpellCommands.CanCastSpell(spellId): bool
+- SpellCommands.GetSpellCooldownRemaining(spellId): double
+- SpellCommands.InterruptCurrentSpell(): void
+- SpellCommands.WaitForCastCompletion(timeoutMs): bool
+- Targeting.SetTarget(entityOrId): bool
+- Targeting.ClearTarget(): void
+- Targeting.WaitForTarget(timeoutMs): bool
+- SpellManager.ResolveSpell(idOrName): SpellData
+- SpellManager.CheckRequirements(spell): bool
+- SpellManager.UpdateCooldown(spellId, duration): void
+- SpellManager.GetCooldownRemaining(spellId): double
+- CastSpell.Send(spellId, targetId): void
+
+**Section sources**
+- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
+- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
+- [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs)
+- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)

.qoder/repowiki/en/content/API Reference/Macro Commands/Targeting Commands.md

@@ -0,0 +1,466 @@
+# Targeting Commands
+
+<cite>
+**Referenced Files in This Document**
+- [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)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.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 Targeting macro commands and their integration with the targeting subsystem. It covers how targets are acquired, validated, persisted, queued, and monitored, and how these capabilities integrate with combat and interaction flows. The focus is on macro command usage patterns, method signatures for various selection criteria, conditional targeting, filtering, multi-target scenarios, queue management, and state monitoring.
+
+## Project Structure
+The targeting system spans macro command definitions, a central targeting manager, a target queue, and network packet abstractions used to interact with the game client.
+
+```mermaid
+graph TB
+subgraph "Macro Commands"
+TC["TargetCommands.cs"]
+HKE["TargetAcquisitionEnemy.cs"]
+HKF["TargetAcquisitionFriend.cs"]
+HKT["Targeting.cs"]
+end
+subgraph "Targeting Core"
+TM["TargetManager.cs"]
+TQ["TargetQueue.cs"]
+TE["Enums.cs"]
+TBD["TargetBodyData.cs"]
+end
+subgraph "Game Objects"
+E["Entity.cs"]
+M["Mobile.cs"]
+I["Item.cs"]
+end
+subgraph "Networking"
+UO["UseObject.cs"]
+CT["CancelTargetCursor.cs"]
+T["Target.cs"]
+TBR["TargetByResource.cs"]
+end
+TC --> TM
+HKE --> TM
+HKF --> TM
+HKT --> TM
+TM --> TQ
+TM --> TE
+TM --> TBD
+TM --> E
+TM --> M
+TM --> I
+TM --> UO
+TM --> CT
+TM --> T
+TM --> TBR
+```
+
+**Diagram 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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)
+
+## Core Components
+- TargetCommands: Macro command entry points for targeting operations (e.g., set current target, add to queue, clear queue). These expose user-facing commands that delegate to the targeting manager.
+- TargetManager: Central orchestrator for acquiring, validating, persisting, and queuing targets. It coordinates with game objects and networking layers.
+- TargetQueue: Manages ordered lists of pending targets and provides operations to enqueue, dequeue, and inspect queue state.
+- Enums and Body Data: Define targeting modes, notoriety filters, body type mappings, and related metadata used by acquisition logic.
+- Game Objects (Entity, Mobile, Item): Provide properties such as UID, name, type, location, and other attributes used for selection and validation.
+- Networking Packets: Represent outgoing targeting actions (use object, cancel cursor, direct target, resource-based target).
+
+Key responsibilities:
+- Acquisition: Find candidates based on UID, name, type, proximity, or resource IDs.
+- Validation: Ensure candidates meet constraints (validity, range, notoriety, ownership).
+- Persistence: Maintain current target and optional persistent sets for later use.
+- Queue Management: Enqueue/dequeue targets and monitor queue state.
+- Integration: Emit appropriate packets to the game client and coordinate with combat/interaction systems.
+
+**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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+
+## Architecture Overview
+The macro layer calls into TargetManager, which uses Entity/Mobile/Item collections to find candidates, applies filters and validation, updates persistence (current target), and enqueues targets via TargetQueue. Network packets are emitted to instruct the client to target an object or cancel the cursor.
+
+```mermaid
+sequenceDiagram
+participant Macro as "Macro Command"
+participant Cmd as "TargetCommands"
+participant Mgr as "TargetManager"
+participant Q as "TargetQueue"
+participant Net as "Networking Packets"
+Macro->>Cmd : Invoke targeting command
+Cmd->>Mgr : AcquireAndValidate(criteria)
+Mgr->>Mgr : Filter and validate candidates
+Mgr-->>Cmd : Selected entity/item
+Cmd->>Mgr : SetCurrent(target)
+Cmd->>Q : Enqueue(target)
+Mgr->>Net : Send UseObject/Target/CancelTargetCursor
+Note over Mgr,Net : Client acknowledges target state
+```
+
+**Diagram 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)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)
+
+## Detailed Component Analysis
+
+### TargetCommands Macro API
+TargetCommands exposes macro-friendly methods for common targeting tasks. Typical operations include:
+- Set current target by UID/name/type/proximity/resource
+- Add one or more targets to the queue
+- Clear the queue
+- Query current target and queue state
+
+Representative method families (described by purpose and parameters; exact signatures are defined in the source file):
+- By identifier
+  - SetTarget(uid)
+  - SetTarget(name)
+  - SetTarget(typeId)
+- By proximity
+  - SetNearest(entityType, maxDistance)
+  - SetNearestNotoriety(notorietyFilter, maxDistance)
+- By resource
+  - SetTargetByResource(resourceId)
+- Queue operations
+  - AddToQueue(uid)
+  - AddToQueueByName(name)
+  - AddToQueueByType(typeId)
+  - AddToQueueNearest(maxDistance)
+  - ClearQueue()
+- State queries
+  - GetCurrentTargetUid()
+  - GetQueueSize()
+  - IsQueueEmpty()
+
+Conditional targeting examples:
+- Only target if within range and not hostile
+- Prefer friendly entities first, then neutral
+- Skip dead or invisible entities
+
+Multi-target scenarios:
+- Enqueue multiple nearby enemies
+- Enqueue all items of a specific type within range
+- Enqueue friends matching a name pattern
+
+Integration notes:
+- After setting a target, the manager emits the appropriate packet to the client.
+- Queue operations update internal state and may trigger follow-up actions (e.g., auto-use on next item).
+
+**Section sources**
+- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
+
+### TargetManager Orchestration
+Responsibilities:
+- Candidate discovery across Entity/Mobile/Item collections
+- Filtering by UID, name, type, notoriety, distance, and custom predicates
+- Validation against game rules (validity, ownership, visibility)
+- Updating current target and notifying listeners
+- Enqueuing targets through TargetQueue
+- Sending network packets to effect targeting
+
+Key behaviors:
+- Proximity calculation uses spatial data from entities.
+- Notoriety checks rely on enums and entity flags.
+- Resource-based targeting maps resource IDs to valid targetable types.
+
+Error handling:
+- Returns failure when no candidates match or validation fails.
+- Provides reasons for failures (e.g., out of range, invalid UID).
+
+**Section sources**
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+
+### TargetQueue Management
+Operations:
+- Enqueue(target)
+- Dequeue()
+- Peek()
+- Contains(target)
+- Remove(target)
+- Clear()
+- Count/IsEmpty
+
+State monitoring:
+- Events or properties to observe changes in size and head element.
+- Useful for chaining actions after a target is consumed.
+
+Persistence:
+- Queue contents can be serialized/deserialized for profile persistence.
+
+**Section sources**
+- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
+
+### Hotkey Targeting Integrations
+These hotkey commands complement macro commands by providing quick access to common targeting patterns:
+- TargetAcquisitionEnemy: Finds nearest enemy based on notoriety and proximity.
+- TargetAcquisitionFriend: Finds nearest friend or ally.
+- Targeting: General-purpose targeting helpers used by both macros and hotkeys.
+
+They typically call into TargetManager with predefined filters and emit the same network packets.
+
+**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)
+
+### Networking and Client Interaction
+Targeting results are communicated to the client using packets:
+- UseObject: Instructs the client to use a specific target.
+- CancelTargetCursor: Cancels any active targeting cursor.
+- Target: Directly sets a target by UID.
+- TargetByResource: Targets by resource ID when applicable.
+
+These packets ensure the client’s UI and state reflect the selected target.
+
+**Section sources**
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)
+
+### Conditional Targeting Flow
+A typical conditional flow:
+- Gather candidates
+- Apply filters (type, notoriety, distance, visibility)
+- Validate (alive, owned, interactable)
+- Select best candidate (nearest, preferred notoriety)
+- Persist current target and enqueue if requested
+- Emit network packet(s)
+
+```mermaid
+flowchart TD
+Start(["Start"]) --> Gather["Gather Candidates"]
+Gather --> Filters{"Apply Filters<br/>UID/Name/Type/Proximity"}
+Filters --> |No matches| Fail["Return Failure"]
+Filters --> |Matches| Validate["Validate Candidates"]
+Validate --> Valid{"Valid?"}
+Valid --> |No| NextCand["Try Next Candidate"]
+NextCand --> Filters
+Valid --> |Yes| Select["Select Best Candidate"]
+Select --> Persist["Persist Current Target"]
+Persist --> Enqueue{"Enqueue?"}
+Enqueue --> |Yes| QAdd["Enqueue(Target)"]
+Enqueue --> |No| SkipQ["Skip Queue"]
+QAdd --> Packet["Send Targeting Packet(s)"]
+SkipQ --> Packet
+Packet --> End(["Done"])
+Fail --> End
+```
+
+**Diagram sources**
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)
+
+## Dependency Analysis
+High-level dependencies:
+- TargetCommands depends on TargetManager for all targeting logic.
+- TargetManager depends on:
+  - Game objects (Entity, Mobile, Item) for candidate data
+  - Targeting enums and body data for filters and mappings
+  - TargetQueue for queue operations
+  - Networking packets to affect client state
+- Hotkey commands depend on TargetManager similarly to macros.
+
+```mermaid
+classDiagram
+class TargetCommands {
++SetTarget(...)
++AddToQueue(...)
++ClearQueue()
++GetCurrentTargetUid()
++GetQueueSize()
+}
+class TargetManager {
++AcquireAndValidate(criteria)
++SetCurrent(target)
++Enqueue(target)
++SendPackets()
+}
+class TargetQueue {
++Enqueue(target)
++Dequeue()
++Peek()
++Contains(target)
++Remove(target)
++Clear()
++Count
+}
+class Entity
+class Mobile
+class Item
+class Enums
+class TargetBodyData
+class UseObject
+class CancelTargetCursor
+class Target
+class TargetByResource
+TargetCommands --> TargetManager : "delegates"
+TargetManager --> TargetQueue : "uses"
+TargetManager --> Entity : "reads"
+TargetManager --> Mobile : "reads"
+TargetManager --> Item : "reads"
+TargetManager --> Enums : "filters"
+TargetManager --> TargetBodyData : "mappings"
+TargetManager --> UseObject : "emits"
+TargetManager --> CancelTargetCursor : "emits"
+TargetManager --> Target : "emits"
+TargetManager --> TargetByResource : "emits"
+```
+
+**Diagram 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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)
+
+## Performance Considerations
+- Candidate gathering should be bounded by spatial locality (e.g., radius checks) to avoid scanning entire world.
+- Precompute distances where possible and short-circuit early on failed filters.
+- Avoid repeated allocations in tight loops; reuse buffers for comparisons.
+- Batch network emissions when performing multiple queue operations to reduce overhead.
+- Debounce rapid successive targeting requests to prevent redundant work.
+
+[No sources needed since this section provides general guidance]
+
+## Troubleshooting Guide
+Common issues and resolutions:
+- No target found: Verify filters (UID/name/type/proximity/notoriety) and ensure entities are visible and valid.
+- Out-of-range errors: Increase max distance or move closer to intended targets.
+- Invalid UID: Confirm the UID exists and belongs to a targetable entity.
+- Cursor stuck: Ensure CancelTargetCursor is sent when aborting a targeting sequence.
+- Queue not draining: Check consumer logic that dequeues and acts on targets.
+
+Diagnostic tips:
+- Log candidate counts before and after filters.
+- Inspect current target and queue size/state.
+- Trace emitted packets to confirm client-side effects.
+
+**Section sources**
+- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+
+## Conclusion
+TargetCommands provide a robust, composable interface for macro-driven targeting. Through TargetManager and TargetQueue, they support precise acquisition, validation, persistence, and queueing, while integrating seamlessly with the game client via targeted network packets. Using the documented APIs and patterns, macros can implement sophisticated targeting strategies including conditional selection, filtering, and multi-target workflows.
+
+[No sources needed since this section summarizes without analyzing specific files]
+
+## Appendices
+
+### Method Signatures Reference
+For exact parameter types and return values, consult the following files:
+- TargetCommands macro API: [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
+- TargetManager orchestration: [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
+- TargetQueue operations: [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
+- Targeting enums and body data: [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs), [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- Game object models: [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs), [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs), [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- Networking packets: [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs), [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs), [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs), [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.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)
+- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
+- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
+- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
+- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
+- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
+- [UseObject.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseObject.cs)
+- [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs)
+- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
+- [TargetByResource.cs](file://ClassicAssist.Shared/UO/Network/Packets/TargetByResource.cs)