Files

T

Beyhan Oğur d5f52cc3d3 first commit

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

20 KiB

Raw Blame History

Macro Commands

**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)

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
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

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

Section sources

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

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

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

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 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

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 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

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 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

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 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

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 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

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 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

Conceptual Overview

The following conceptual diagram illustrates how macro commands integrate with the broader system:

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.

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

Section sources

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

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

20 KiB Raw Blame History

Macro Commands

Table of Contents

Introduction

Project Structure

Core Components

Architecture Overview

Detailed Component Analysis

ActionCommands

MovementCommands

TargetCommands

SpellCommands

MobileCommands

ObjectCommands

Conceptual Overview

Dependency Analysis

Performance Considerations

Troubleshooting Guide

Conclusion

Appendices

Command Registration Process

20 KiB

Raw Blame History