Files

T

Beyhan Oğur d5f52cc3d3 first commit

2026-09-03 04:45:36 +03:00

26 KiB

Raw Permalink Blame History

Spell Commands

**Referenced Files in This Document** - [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs) - [InterruptSpellCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/InterruptSpellCommand.cs) - [CastLastSpell.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/CastLastSpell.cs) - [ClearObjectQueue.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/ClearObjectQueue.cs) - [Targeting.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/Targeting.cs) - [SpellManager.cs](file://ClassicAssist.Shared/Data/Spells/SpellManager.cs) - [SpellData.cs](file://ClassicAssist.Shared/Data/Spells/SpellData.cs) - [TargetManager.cs](file://ClassicAssist.Shared/Data/Targeting/TargetManager.cs) - [TargetQueue.cs](file://ClassicAssist.Shared/Data/Targeting/TargetQueue.cs) - [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs) - [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs) - [CancelTargetCursor.cs](file://ClassicAssist.Shared/UO/Network/Packets/CancelTargetCursor.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs) - [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs) - [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs) - [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs) - [MobileCollection.cs](file://ClassicAssist.Shared/UO/Objects/MobileCollection.cs) - [EntityCollection.cs](file://ClassicAssist.Shared/UO/Objects/EntityCollection.cs)

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction

This document explains spell casting commands within the ClassicAssist.Avalonia macro system. It covers how to cast spells, cancel casts, queue targets, manage mana and cooldowns, and integrate with targeting systems for precise application. It also provides examples for combat rotations, healing automation, buff management, and complex sequences, along with guidance on interruptions, error recovery, and performance optimization for rapid casting.

Project Structure

The spell command functionality spans several modules:

Macro commands that expose user-facing actions (cast, cancel, last spell, clear queue).
Targeting subsystem for selecting entities and queuing targets.
Spell data and manager for lookup, validation, and metadata.
Network layer for sending cast packets and handling responses.
Macro engine integration for execution context and timing.

graph TB
subgraph "Macros"
MC["MacroInvoker"]
MM["MacroManager"]
SCmd["SpellCommands"]
ICmd["InterruptSpellCommand"]
CLS["CastLastSpell"]
COQ["ClearObjectQueue"]
end
subgraph "Targeting"
TM["TargetManager"]
TQ["TargetQueue"]
TgCmd["Targeting"]
end
subgraph "Spells"
SM["SpellManager"]
SD["SpellData"]
end
subgraph "Network"
APQ["ActionPacketQueue"]
CS["CastSpell Packet"]
CTC["CancelTargetCursor Packet"]
IPH["IncomingPacketHandlers"]
OPH["OutgoingPacketHandlers"]
end
subgraph "Game Objects"
PM["PlayerMobile"]
MColl["MobileCollection"]
EColl["EntityCollection"]
end
SCmd --> SM
SCmd --> TM
SCmd --> APQ
ICmd --> TM
CLS --> SM
CLS --> TM
COQ --> TQ
TgCmd --> TM
TM --> TQ
SM --> SD
APQ --> CS
APQ --> CTC
IPH --> TM
OPH --> APQ
SCmd --> PM
SCmd --> MColl
SCmd --> EColl

Diagram sources

Section sources

Core Components

SpellCommands: Exposes macro commands to cast spells by name or ID, select targets, control positioning, and manage timing. Integrates with SpellManager for validation and TargetManager for selection.
InterruptSpellCommand: Cancels an ongoing cast or target cursor via network packet.
CastLastSpell: Re-casts the most recently used spell using stored context.
ClearObjectQueue: Clears pending target queue entries to reset state.
Targeting: Provides helper hotkey commands for entity selection and targeting workflows.
SpellManager/SpellData: Central registry of spells, their properties, costs, and constraints.
TargetManager/TargetQueue: Manages current target and queued targets for multi-target spells.
ActionPacketQueue: Serializes outgoing actions (casts, cancels) to ensure proper ordering and rate limiting.
Incoming/Outgoing Packet Handlers: Bridge between game events and macro logic (e.g., update player status, handle cast confirmations).
PlayerMobile/MobileCollection/EntityCollection: Provide runtime access to player state and world entities for targeting and conditions.

Section sources

Architecture Overview

The macro system composes high-level commands into low-level network actions through a layered architecture:

Command Layer: Macro commands parse parameters and validate inputs.
Domain Layer: Spell and targeting managers enforce rules and maintain state.
Network Layer: ActionPacketQueue serializes packets; handlers react to server responses.
Game State Layer: Entities and collections provide real-time information for decisions.

sequenceDiagram
participant Macro as "MacroInvoker"
participant Cmd as "SpellCommands"
participant SMan as "SpellManager"
participant TMan as "TargetManager"
participant Aq as "ActionPacketQueue"
participant Net as "Network Packets"
participant Server as "Game Server"
Macro->>Cmd : "spell_cast(spell_name, target, position, delay)"
Cmd->>SMan : "resolve_spell(spell_name)"
SMan-->>Cmd : "SpellData"
Cmd->>TMan : "select_target(target_spec)"
TMan-->>Cmd : "target_id or null"
Cmd->>Aq : "enqueue(CastSpell)"
Aq->>Net : "send(CastSpell)"
Net->>Server : "CastSpell packet"
Server-->>Net : "Cast result/status"
Net-->>Aq : "acknowledge"
Aq-->>Cmd : "success/failure"
Cmd-->>Macro : "result"

Diagram sources

Detailed Component Analysis

Spell Casting Command

Purpose: Cast a named spell with optional target, positioning, and timing controls.
Key responsibilities:
- Resolve spell by name or ID via SpellManager.
- Validate prerequisites (mana, cooldown, range).
- Select target using TargetManager helpers.
- Enqueue CastSpell packet via ActionPacketQueue.
- Handle success/failure and return results to macros.
Parameters typically include:
- Spell identifier (name or ID).
- Target specification (entity reference, name filter, or auto-select).
- Positional offset or relative coordinates for ground-targeted spells.
- Delay or wait options to pace casting.
Error handling:
- Invalid spell name/ID.
- Insufficient mana or out-of-range.
- Cooldown not expired.
- Target not found or invalid.
- Network send failure or server rejection.

flowchart TD
Start(["spell_cast entry"]) --> Resolve["Resolve spell by name/ID"]
Resolve --> Valid{"Spell valid?"}
Valid --> |No| ErrInvalid["Return error: invalid spell"]
Valid --> |Yes| CheckMana["Check mana cost and availability"]
CheckMana --> ManaOK{"Enough mana?"}
ManaOK --> |No| ErrMana["Return error: insufficient mana"]
ManaOK --> |Yes| CheckCD["Check spell cooldown"]
CheckCD --> CDOK{"Cooldown ready?"}
CDOK --> |No| ErrCD["Return error: spell on cooldown"]
CDOK --> |Yes| SelectTarget["Select target or position"]
SelectTarget --> TargetOK{"Target resolved?"}
TargetOK --> |No| ErrTarget["Return error: target not found"]
TargetOK --> |Yes| Enqueue["Enqueue CastSpell packet"]
Enqueue --> Send["Send via ActionPacketQueue"]
Send --> Result{"Server accepted?"}
Result --> |No| ErrServer["Return error: server rejected"]
Result --> |Yes| Done(["Success"])

Diagram sources

Section sources

Cancellation and Interruption

InterruptSpellCommand: Sends CancelTargetCursor to abort a pending target cursor or cast initiation.
Use cases:
- Stop a misfired cast.
- Cancel targeting when switching priorities.
- Recover from stuck states where the client expects a target input.

sequenceDiagram
participant Macro as "MacroInvoker"
participant Int as "InterruptSpellCommand"
participant TMan as "TargetManager"
participant Aq as "ActionPacketQueue"
participant Net as "Network Packets"
participant Server as "Game Server"
Macro->>Int : "interrupt_spell()"
Int->>TMan : "check active target/cursor"
Int->>Aq : "enqueue(CancelTargetCursor)"
Aq->>Net : "send(CancelTargetCursor)"
Net->>Server : "CancelTargetCursor packet"
Server-->>Net : "acknowledge"
Net-->>Aq : "success"
Aq-->>Int : "done"
Int-->>Macro : "interrupt complete"

Diagram sources

Section sources

Last Spell Recast

CastLastSpell: Reuses the most recent spell context (ID, target, position) to recast quickly.
Benefits:
- Simplifies repetitive casting patterns.
- Reduces parsing overhead in tight loops.
Typical usage:
- In combat rotations after successful hits.
- For quick follow-up casts when conditions are met.

sequenceDiagram
participant Macro as "MacroInvoker"
participant CLS as "CastLastSpell"
participant SMan as "SpellManager"
participant TMan as "TargetManager"
participant Aq as "ActionPacketQueue"
participant Net as "Network Packets"
Macro->>CLS : "cast_last_spell()"
CLS->>SMan : "lookup last spell data"
CLS->>TMan : "restore last target if needed"
CLS->>Aq : "enqueue(CastSpell with last context)"
Aq->>Net : "send(CastSpell)"
Net-->>Aq : "acknowledge"
Aq-->>CLS : "success/failure"
CLS-->>Macro : "result"

Diagram sources

Section sources

Queue Management

ClearObjectQueue: Resets pending target queue entries to avoid stale targets.
TargetQueue: Maintains ordered list of targets for multi-target spells or batch operations.
Integration:
- Before casting area effects, clear queue to ensure fresh selection.
- After successful casts, optionally clear queue to prevent accidental reapplication.

flowchart TD
Start(["clear_object_queue"]) --> Check["Check if queue has items"]
Check --> HasItems{"Has items?"}
HasItems --> |No| EndEmpty(["Nothing to clear"])
HasItems --> |Yes| Reset["Reset TargetQueue state"]
Reset --> Notify["Notify TargetManager of cleared state"]
Notify --> EndDone(["Queue cleared"])

Diagram sources

Section sources

Targeting Helpers

Targeting: Provides commands to select entities by criteria (friend/enemy), refine selection, and prepare for targeted spells.
Use cases:
- Pre-select a specific mobile before casting.
- Switch targets dynamically based on health thresholds.
- Combine with positioning offsets for ground-targeted spells.

Section sources

Dependency Analysis

Key relationships:

SpellCommands depends on SpellManager for spell resolution and validation, TargetManager for selection, and ActionPacketQueue for reliable network dispatch.
InterruptSpellCommand relies on TargetManager to determine whether a cursor is active and sends CancelTargetCursor via ActionPacketQueue.
CastLastSpell uses SpellManager and TargetManager to reconstruct prior cast context.
ClearObjectQueue interacts with TargetQueue and TargetManager to reset state.
Incoming/Outgoing Packet Handlers bridge server events and macro logic, updating PlayerMobile and related collections.

classDiagram
class SpellCommands {
+cast(spellName, targetSpec, position, delay)
+validatePrerequisites()
+enqueueCast()
}
class InterruptSpellCommand {
+interrupt()
}
class CastLastSpell {
+recast()
}
class ClearObjectQueue {
+clear()
}
class Targeting {
+selectByCriteria()
+refineSelection()
}
class SpellManager {
+resolve(nameOrId)
+getCostAndCooldown()
}
class TargetManager {
+setTarget()
+getActiveTarget()
+clear()
}
class TargetQueue {
+push()
+pop()
+clear()
}
class ActionPacketQueue {
+enqueue(packet)
+flush()
}
class IncomingPacketHandlers
class OutgoingPacketHandlers
class PlayerMobile
class MobileCollection
class EntityCollection
SpellCommands --> SpellManager : "resolves spell"
SpellCommands --> TargetManager : "selects target"
SpellCommands --> ActionPacketQueue : "enqueues cast"
InterruptSpellCommand --> TargetManager : "checks cursor"
InterruptSpellCommand --> ActionPacketQueue : "cancels"
CastLastSpell --> SpellManager : "last spell data"
CastLastSpell --> TargetManager : "restore target"
ClearObjectQueue --> TargetQueue : "clears queue"
ClearObjectQueue --> TargetManager : "notifies"
Targeting --> TargetManager : "updates target"
IncomingPacketHandlers --> PlayerMobile : "updates state"
OutgoingPacketHandlers --> ActionPacketQueue : "dispatches"
SpellCommands --> PlayerMobile : "reads stats"
SpellCommands --> MobileCollection : "finds entities"
SpellCommands --> EntityCollection : "filters objects"

Diagram sources

Section sources

Performance Considerations

Batch casting:
- Use ActionPacketQueue to serialize casts and avoid flooding the network.
- Group multiple casts with minimal delays to maximize throughput while respecting server-side limits.
Rapid spell casting:
- Prefer CastLastSpell for repeated casts to reduce parameter parsing overhead.
- Cache frequently used spell IDs instead of resolving by name repeatedly.
Target selection efficiency:
- Pre-select targets using Targeting helpers to minimize lookups during critical moments.
- Clear queues before area-effect casts to prevent stale selections.
Mana and cooldown checks:
- Perform prerequisite checks early to avoid unnecessary network calls.
- Use SpellManager’s cached data for cost and cooldown values.
Timing controls:
- Insert small delays between casts to accommodate server processing and animation locks.
- Avoid excessive waits that degrade responsiveness.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

Spell fails due to insufficient mana:
- Verify PlayerMobile’s mana pool and spell cost via SpellManager.
- Add mana checks before casting and fallback to non-mana actions.
Spell on cooldown:
- Check cooldown status via SpellManager and schedule retries after expiration.
Target not found:
- Use Targeting helpers to refine selection criteria.
- Ensure MobileCollection and EntityCollection filters match expected entities.
Stuck target cursor:
- Invoke InterruptSpellCommand to cancel pending cursors.
- Confirm CancelTargetCursor was sent and acknowledged.
Network errors:
- Monitor OutgoingPacketHandlers for send failures.
- Retry failed casts with backoff and error logging.
Recovery strategies:
- Implement retry loops with exponential backoff for transient failures.
- Log detailed context (spell ID, target, position, delay) for diagnostics.

Section sources

Conclusion

The spell command system integrates macro-level actions with robust domain logic and reliable networking. By leveraging SpellManager, TargetManager, and ActionPacketQueue, macros can perform precise, efficient, and resilient spell casting. Proper use of cancellation, queue management, and timing controls enables advanced automation for combat, healing, and buffs, while troubleshooting practices ensure stability under dynamic conditions.

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

Appendices

Example Patterns

Combat rotation:
- Loop: check enemy presence, cast primary spell, recast last spell if available, interrupt if interrupted, clear queue, delay, repeat.
Healing automation:
- Monitor ally health via MobileCollection, cast heal when below threshold, prioritize self-heal if necessary, cancel conflicting casts.
Buff management:
- Apply buffs to allies with missing effects, refresh before expiration, avoid redundant casts, manage mana budget.
Complex sequences:
- Chain multiple spells with positional offsets, stagger timings, and conditional branching based on server responses.

[No sources needed since this section provides conceptual examples]

26 KiB Raw Permalink Blame History Unescape Escape

Spell Commands

Table of Contents

Introduction

Project Structure

Core Components

Architecture Overview

Detailed Component Analysis

Spell Casting Command

Cancellation and Interruption

Last Spell Recast

Queue Management

Targeting Helpers

Dependency Analysis

Performance Considerations

Troubleshooting Guide

Conclusion

Appendices

Example Patterns

26 KiB

Raw Permalink Blame History