# Targeting Commands

<cite>
**Referenced Files in This Document**
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.cs)
</cite>

## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)

## Introduction
This document explains how targeting commands work within the ClassicAssist.Avalonia macro system. It covers selection by type, distance, name, color, and entity properties; advanced scenarios such as conditional targeting, priority-based selection, and dynamic target switching; and operational concerns like validation, timeouts, fallback strategies, performance with large collections, and memory management. The goal is to help you build robust combat automation, resource gathering, and social interaction macros that are efficient and resilient.

## Project Structure
The targeting subsystem spans shared data structures, hotkey command implementations, and macro command handlers:
- Hotkey commands for acquiring targets (enemy/friend)
- Macro-level targeting commands
- Core targeting manager and queue
- Entity collections and base types used for filtering and selection

```mermaid
graph TB
subgraph "Hotkey Commands"
TAE["TargetAcquisitionEnemy.cs"]
TAF["TargetAcquisitionFriend.cs"]
TGT["Targeting.cs"]
end
subgraph "Macro Commands"
MC["TargetCommands.cs"]
end
subgraph "Targeting Core"
TM["TargetManager.cs"]
TQ["TargetQueue.cs"]
TE["Enums.cs"]
TBD["TargetBodyData.cs"]
end
subgraph "Entities"
EC["EntityCollection.cs"]
MCOL["MobileCollection.cs"]
MOB["Mobile.cs"]
ENT["Entity.cs"]
end
TAE --> TM
TAF --> TM
TGT --> TM
MC --> TM
TM --> TQ
TM --> EC
TM --> MCOL
MCOL --> MOB
MOB --> ENT
```

**Diagram sources**
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)

**Section sources**
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)

## Core Components
- Targeting hotkey commands: Provide quick acquisition of enemies or friends via hotkeys. They typically query nearby mobiles and issue a targeted action.
- Macro targeting commands: Expose higher-level commands usable from scripts/macros to select targets based on criteria and perform actions.
- TargetManager: Central coordination for selecting, validating, queuing, and issuing targets.
- TargetQueue: Manages ordered sequences of targets for batched or sequential operations.
- Enums and body data: Define selectable categories, notoriety rules, and body-type mappings used during selection.
- Entity collections: Provide filtered views over entities/mobs for efficient querying.

Key responsibilities:
- Filtering by type, distance, name, color, and properties
- Priority and conditional selection
- Validation and timeout handling
- Queueing and execution of targeting actions

**Section sources**
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)

## Architecture Overview
The targeting architecture separates user-facing commands (hotkeys and macros) from core selection logic and execution. Selection uses entity collections and filters; execution uses the target manager and queue.

```mermaid
sequenceDiagram
participant User as "User/Macro"
participant HK as "Hotkey Command"
participant MC as "Macro Command"
participant TM as "TargetManager"
participant COL as "Entity/Mobile Collection"
participant Q as "TargetQueue"
participant Game as "Game Client"
User->>HK : Trigger hotkey
HK->>TM : Acquire target (criteria)
TM->>COL : Filter by type/distance/name/color/properties
COL-->>TM : Candidate set
TM->>TM : Apply priority/conditions
TM->>Q : Enqueue selected target(s)
Q->>Game : Issue target action(s)
Game-->>TM : Acknowledge/Status
TM-->>HK : Result
User->>MC : Call macro targeting command
MC->>TM : Select target(s) with advanced criteria
TM->>COL : Filter + sort + validate
TM->>Q : Enqueue or execute immediately
Q->>Game : Send target packets
Game-->>TM : Responses
TM-->>MC : Outcome and metadata
```

**Diagram sources**
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)

## Detailed Component Analysis

### Hotkey Target Acquisition (Enemy/Friend)
These commands provide fast, context-aware targeting for common gameplay loops. They typically:
- Determine player position and range
- Query nearby mobiles
- Filter by notoriety or friend lists
- Issue a targeted attack or assist action

```mermaid
flowchart TD
Start(["Hotkey Trigger"]) --> GetPlayer["Get Player Position"]
GetPlayer --> QueryNearby["Query Nearby Mobiles"]
QueryNearby --> FilterNotoriety{"Filter by Notoriety/Friends?"}
FilterNotoriety --> |Yes| ApplyRules["Apply Rules"]
FilterNotoriety --> |No| SkipRules["Skip Rules"]
ApplyRules --> BestCandidate["Select Best Candidate"]
SkipRules --> BestCandidate
BestCandidate --> IssueAction["Issue Target Action"]
IssueAction --> End(["Done"])
```

**Diagram sources**
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)

**Section sources**
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)

### Macro Targeting Commands
Macro commands expose richer selection capabilities suitable for automation:
- Type-based selection (e.g., specific bodies or categories)
- Distance-based selection (nearest, farthest, within radius)
- Name-based selection (exact/partial match)
- Color/hue-based selection
- Property-based selection (flags, stats, custom properties)
- Conditional targeting (if/else branches based on environment/state)
- Priority-based selection (rank candidates by multiple criteria)
- Dynamic target switching (rotate among valid targets)

```mermaid
classDiagram
class TargetManager {
+SelectByType(criteria)
+SelectByDistance(radius, order)
+SelectByName(pattern)
+SelectByColor(hue)
+SelectByProperties(filter)
+Validate(target)
+Enqueue(targets)
+ExecuteNext()
}
class TargetQueue {
+Add(target)
+Remove(target)
+Peek()
+Dequeue()
+Count
}
class EntityCollection {
+FilteredView(filters)
+OrderBy(comparer)
+FirstOrDefault(predicate)
}
class MobileCollection {
+Nearby(playerPos, radius)
+ByNotoriety(rules)
+ByFriends(list)
}
TargetManager --> TargetQueue : "uses"
TargetManager --> EntityCollection : "queries"
TargetManager --> MobileCollection : "queries"
```

**Diagram sources**
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)

**Section sources**
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)

### Target Body Data and Enums
Selection often relies on predefined body categories and enums:
- Body-to-category mapping for creature/item classification
- Notoriety and faction enums for friend/enemy logic
- Flags and attributes used in property-based filtering

```mermaid
classDiagram
class TargetBodyData {
+Map(bodyId) Category
+IsCreature(bodyId) bool
+IsItem(bodyId) bool
}
class Enums {
<<enumeration>>
Notoriety
TargetCategory
SelectionOrder
}
TargetBodyData --> Enums : "uses"
```

**Diagram sources**
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)

**Section sources**
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)

### Advanced Targeting Scenarios

#### Conditional Targeting
Use conditions to choose between different target sets depending on state:
- If low health, prioritize friendly healers
- If no valid enemy, switch to nearest resource node
- If line-of-sight fails, fall back to ranged option

```mermaid
flowchart TD
Start(["Start"]) --> CheckState["Evaluate Conditions"]
CheckState --> ConditionA{"Condition A true?"}
ConditionA --> |Yes| SetA["Set Criteria A"]
ConditionA --> |No| ConditionB{"Condition B true?"}
ConditionB --> |Yes| SetB["Set Criteria B"]
ConditionB --> |No| Fallback["Fallback Criteria"]
SetA --> Select["Select Targets"]
SetB --> Select
Fallback --> Select
Select --> Validate["Validate & Sort"]
Validate --> Execute["Execute/Queue"]
Execute --> End(["End"])
```

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

#### Priority-Based Selection
Rank candidates using multiple criteria:
- Primary: proximity
- Secondary: notoriety
- Tertiary: resource availability or item quality

```mermaid
flowchart TD
Start(["Candidates"]) --> Rank1["Sort by Proximity"]
Rank1 --> Rank2["Stable Sort by Notoriety"]
Rank2 --> Rank3["Stable Sort by Quality/Availability"]
Rank3 --> PickTop["Pick Top Ranked"]
PickTop --> Validate["Validate Target"]
Validate --> Execute["Execute/Queue"]
Execute --> End(["End"])
```

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

#### Dynamic Target Switching
Rotate among valid targets to distribute workload or avoid stale locks:
- Maintain a list of eligible targets
- On each cycle, pick next candidate
- Re-validate before acting
- Reset rotation when invalid

```mermaid
sequenceDiagram
participant Loop as "Automation Loop"
participant TM as "TargetManager"
participant Q as "TargetQueue"
participant Game as "Game Client"
Loop->>TM : Get Next Candidate
TM->>TM : Rotate Index
TM->>TM : Validate Candidate
alt Valid
TM->>Q : Enqueue Candidate
Q->>Game : Issue Action
Game-->>TM : Status
else Invalid
TM->>TM : Remove From Rotation
TM->>Loop : Retry Next
end
```

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

### Examples

#### Combat Automation
- Enemy acquisition by notoriety and distance
- Conditional switching if primary target dies or becomes invalid
- Fallback to nearest hostile if none found

#### Resource Gathering
- Select by type (resource nodes), color (ore/gems), and distance
- Prioritize highest yield or closest node
- Fallback to inventory check and vendor if none available

#### Social Interactions
- Friend selection by friend list and proximity
- Conditional targeting based on chat presence or party status
- Fallback to last known friend if current unavailable

[No sources needed since these examples illustrate usage patterns without analyzing specific files]

### Target Validation, Timeouts, and Fallbacks
- Validation checks include existence, visibility, range, and game-state constraints
- Timeout handling prevents macros from hanging indefinitely when targets disappear
- Fallback strategies ensure continuity: alternate targets, change criteria, or abort gracefully

```mermaid
flowchart TD
Start(["Select Target"]) --> Validate["Validate Target"]
Validate --> Valid{"Valid?"}
Valid --> |Yes| Proceed["Proceed to Action"]
Valid --> |No| TimeoutCheck{"Timeout Reached?"}
TimeoutCheck --> |Yes| Fallback["Apply Fallback Strategy"]
TimeoutCheck --> |No| Retry["Retry With Adjusted Criteria"]
Retry --> Validate
Fallback --> End(["Exit or Continue"])
Proceed --> End
```

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

**Section sources**
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.cs)

## Dependency Analysis
The following diagram highlights key dependencies among targeting components and entity collections.

```mermaid
graph LR
TAC["TargetAcquisitionEnemy.cs"] --> TM["TargetManager.cs"]
TAF["TargetAcquisitionFriend.cs"] --> TM
TGT["Targeting.cs"] --> TM
MC["TargetCommands.cs"] --> TM
TM --> TQ["TargetQueue.cs"]
TM --> EC["EntityCollection.cs"]
TM --> MCOL["MobileCollection.cs"]
MCOL --> MOB["Mobile.cs"]
MOB --> ENT["Entity.cs"]
TM --> ENUMS["Enums.cs"]
TM --> BODY["TargetBodyData.cs"]
```

**Diagram sources**
- [TargetAcquisitionEnemy.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionEnemy.cs)
- [TargetAcquisitionFriend.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/TargetAcquisitionFriend.cs)
- [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs)
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)

**Section sources**
- [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs)
- [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs)
- [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)
- [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs)
- [Mobile.cs](file://ClassicAssist.Shared/UO/Objects/Mobile.cs)
- [Entity.cs](file://ClassicAssist.Shared/UO/Objects/Entity.cs)
- [Enums.cs](file://ClassicAssist.Shared/Data/Targeting/Enums.cs)
- [TargetBodyData.cs](file://ClassicAssist.Shared/Data/Targeting/TargetBodyData.cs)

## Performance Considerations
When working with large entity collections:
- Prefer filtered views and early pruning (distance, notoriety, type) to reduce candidate sets
- Use stable multi-criteria sorting to minimize re-scans
- Avoid repeated allocations; reuse comparators and filter objects where possible
- Batch enqueue operations instead of issuing individual actions per candidate
- Implement timeouts and short-circuit evaluation to prevent long-running selections
- Monitor memory pressure by limiting retained references to transient candidates

Best practices:
- Cache frequently used filters and comparators
- Limit search radius for nearby queries
- Defer expensive property checks until necessary
- Use queues to decouple selection from execution

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- No targets found: Verify filters (type, color, name), distance radius, and notoriety settings
- Stale targets: Ensure validation runs before each action and implement rotation/reset logic
- Lag spikes: Reduce collection size via tighter filters; avoid heavy computations in hot paths
- Inconsistent behavior: Add logging around selection steps and timeouts; confirm game state changes

Diagnostic tips:
- Inspect candidate counts after each filter stage
- Log reasons for rejection (out of range, invalid notoriety, missing properties)
- Confirm queue depth and execution timing

**Section sources**
- [TargetCommandTests.cs](file://ClassicAssist.Tests/MacroCommands/TargetCommandTests.cs)

## Conclusion
The targeting subsystem combines flexible filtering, prioritization, and queue-driven execution to support robust automation across combat, gathering, and social interactions. By applying conditional logic, priority ranking, and strong validation with timeouts and fallbacks, macros can remain responsive and efficient even under heavy load. Adhering to performance best practices ensures smooth operation with large entity collections and minimizes memory overhead.