Beyhan Oğur
22 KiB
22 KiB
Targeting Commands
**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)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- 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.
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
- TargetManager.cs
- TargetQueue.cs
- Enums.cs
- TargetBodyData.cs
- Mobile.cs
- Item.cs
- Entity.cs
- TargetAcquisitionEnemy.cs
- TargetAcquisitionFriend.cs
- Targeting.cs
- UseObject.cs
- CancelTargetCursor.cs
- Target.cs
- TargetByResource.cs
Section sources
- TargetCommands.cs
- TargetManager.cs
- TargetQueue.cs
- Enums.cs
- TargetBodyData.cs
- Mobile.cs
- Item.cs
- Entity.cs
- TargetAcquisitionEnemy.cs
- TargetAcquisitionFriend.cs
- Targeting.cs
- UseObject.cs
- CancelTargetCursor.cs
- Target.cs
- 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
- TargetManager.cs
- TargetQueue.cs
- Enums.cs
- TargetBodyData.cs
- Mobile.cs
- Item.cs
- 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.
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
- TargetManager.cs
- TargetQueue.cs
- UseObject.cs
- CancelTargetCursor.cs
- Target.cs
- 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
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
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
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
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
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)
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
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.
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
- TargetManager.cs
- TargetQueue.cs
- Enums.cs
- TargetBodyData.cs
- Mobile.cs
- Item.cs
- Entity.cs
- UseObject.cs
- CancelTargetCursor.cs
- Target.cs
- TargetByResource.cs
Section sources
- TargetCommands.cs
- TargetManager.cs
- TargetQueue.cs
- Enums.cs
- TargetBodyData.cs
- Mobile.cs
- Item.cs
- Entity.cs
- UseObject.cs
- CancelTargetCursor.cs
- Target.cs
- 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
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
- TargetManager orchestration: TargetManager.cs
- TargetQueue operations: TargetQueue.cs
- Targeting enums and body data: Enums.cs, TargetBodyData.cs
- Game object models: Entity.cs, Mobile.cs, Item.cs
- Networking packets: UseObject.cs, CancelTargetCursor.cs, Target.cs, TargetByResource.cs
Section sources