first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,680 @@
|
||||
# API Reference
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [UseSkill.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseSkill.cs)
|
||||
- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [MainCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MainCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [GumpCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/GumpCommands.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [ListCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ListCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [RegionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/RegionCommands.cs)
|
||||
- [SkillCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SkillCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [WandCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/WandCommands.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
- [Menu.cs](file://ClassicAssist.Shared/UO/Objects/Menu.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [PacketReader.cs](file://ClassicAssist.Shared/UO/Data/PacketReader.cs)
|
||||
- [PacketWriter.cs](file://ClassicAssist.Shared/UO/Data/PacketWriter.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. Introduction
|
||||
2. Project Structure
|
||||
3. Core Components
|
||||
4. Architecture Overview
|
||||
5. Detailed Component Analysis
|
||||
6. Dependency Analysis
|
||||
7. Performance Considerations
|
||||
8. Troubleshooting Guide
|
||||
9. Conclusion
|
||||
10. Appendices
|
||||
|
||||
## Introduction
|
||||
This document provides a comprehensive API reference for ClassicAssist.Avalonia, focusing on public interfaces and extension points across three primary areas:
|
||||
- Engine API for application lifecycle management
|
||||
- Network API for packet handling and game communication
|
||||
- UI API for cross-platform interface operations
|
||||
|
||||
It also includes a complete macro command reference with method signatures, parameter documentation, return values, and usage examples. Extension points such as plugin interfaces, event hooks, and configuration options are documented alongside data models and their relationships. Thread safety considerations, performance implications, version compatibility notes, and migration guidance are included to support robust integration.
|
||||
|
||||
## Project Structure
|
||||
The repository is organized into multiple projects:
|
||||
- ClassicAssist.Avalonia: Avalonia-based UI entry point and platform-specific integrations
|
||||
- ClassicAssist.Shared: Shared logic including engine core, networking, macros, hotkeys, filters, and UO objects
|
||||
- ClassicAssist: WPF-based UI (legacy)
|
||||
- ClassicAssist.Launcher: Launcher functionality
|
||||
- ClassicAssist.Tests and ClassicAssist.UITest: Test suites
|
||||
- ClassicAssist.Updater: Update utilities
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Avalonia UI"
|
||||
A_Program["Program.cs"]
|
||||
A_App["App.axaml.cs"]
|
||||
A_Engine["Engine.cs"]
|
||||
A_Dispatcher["AvaloniaDispatcher.cs"]
|
||||
A_Invoker["AvaloniaUIInvoker.cs"]
|
||||
end
|
||||
subgraph "Shared Core"
|
||||
S_Engine["Engine.cs"]
|
||||
S_IDispatcher["IDispatcher.cs"]
|
||||
S_IUIInvoker["IUIInvoker.cs"]
|
||||
S_MacroMgr["MacroManager.cs"]
|
||||
S_MacroInv["MacroInvoker.cs"]
|
||||
S_HotkeyMgr["HotkeyManager.cs"]
|
||||
S_IncPktHdl["IncomingPacketHandlers.cs"]
|
||||
S_OutPktHdl["OutgoingPacketHandlers.cs"]
|
||||
S_IncPktFilt["IncomingPacketFilters.cs"]
|
||||
S_ActionQ["ActionPacketQueue.cs"]
|
||||
end
|
||||
subgraph "UO Networking"
|
||||
U_BasePkt["BasePacket.cs"]
|
||||
U_UseSkill["UseSkill.cs"]
|
||||
U_Target["Target.cs"]
|
||||
U_CastSpell["CastSpell.cs"]
|
||||
U_PktReader["PacketReader.cs"]
|
||||
U_PktWriter["PacketWriter.cs"]
|
||||
end
|
||||
subgraph "UO Objects"
|
||||
O_Entity["Entity.cs"]
|
||||
O_Item["Item.cs"]
|
||||
O_Mobile["Mobile.cs"]
|
||||
O_Player["PlayerMobile.cs"]
|
||||
O_Gump["Gump.cs"]
|
||||
O_Menu["Menu.cs"]
|
||||
O_Property["Property.cs"]
|
||||
end
|
||||
A_Program --> A_Engine
|
||||
A_App --> A_Engine
|
||||
A_Engine --> S_Engine
|
||||
A_Dispatcher --> S_IDispatcher
|
||||
A_Invoker --> S_IUIInvoker
|
||||
S_Engine --> S_IncPktHdl
|
||||
S_Engine --> S_OutPktHdl
|
||||
S_Engine --> S_IncPktFilt
|
||||
S_Engine --> S_ActionQ
|
||||
S_IncPktHdl --> U_BasePkt
|
||||
S_OutPktHdl --> U_BasePkt
|
||||
U_UseSkill --> U_BasePkt
|
||||
U_Target --> U_BasePkt
|
||||
U_CastSpell --> U_BasePkt
|
||||
U_PktReader --> U_BasePkt
|
||||
U_PktWriter --> U_BasePkt
|
||||
O_Entity --> O_Item
|
||||
O_Entity --> O_Mobile
|
||||
O_Mobile --> O_Player
|
||||
O_Gump --> O_Menu
|
||||
O_Property --> O_Entity
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [UseSkill.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseSkill.cs)
|
||||
- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [PacketReader.cs](file://ClassicAssist.Shared/UO/Data/PacketReader.cs)
|
||||
- [PacketWriter.cs](file://ClassicAssist.Shared/UO/Data/PacketWriter.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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
- [Menu.cs](file://ClassicAssist.Shared/UO/Objects/Menu.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
|
||||
## Core Components
|
||||
This section documents the primary APIs exposed by ClassicAssist.Avalonia and shared components.
|
||||
|
||||
### Engine API (Application Lifecycle Management)
|
||||
- Entry points:
|
||||
- Program.cs initializes the Avalonia application and starts the engine.
|
||||
- App.axaml.cs configures application resources and services.
|
||||
- Engine.cs (Avalonia) bridges Avalonia-specific concerns to the shared Engine.
|
||||
- Responsibilities:
|
||||
- Application startup and shutdown coordination
|
||||
- Dispatcher and UI invoker initialization
|
||||
- Integration with network subsystems and macro system
|
||||
- Key interfaces:
|
||||
- IDispatcher: Cross-thread UI dispatch abstraction
|
||||
- IUIInvoker: Platform-specific UI invocation methods
|
||||
|
||||
Usage patterns:
|
||||
- Initialize the engine early in application startup.
|
||||
- Use the dispatcher to marshal UI updates from background threads.
|
||||
- Invoke UI actions via the UI invoker when needed.
|
||||
|
||||
**Section sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
|
||||
### Network API (Packet Handling)
|
||||
- Incoming packets:
|
||||
- IncomingPacketHandlers.cs registers handlers for server-to-client packets.
|
||||
- IncomingPacketFilters.cs applies filtering rules before processing.
|
||||
- Outgoing packets:
|
||||
- OutgoingPacketHandlers.cs manages client-to-server packet sending.
|
||||
- Packet queue:
|
||||
- ActionPacketQueue.cs serializes and prioritizes outgoing actions.
|
||||
- Packet types:
|
||||
- BasePacket.cs defines common packet structure and serialization helpers.
|
||||
- Specific packets include UseSkill.cs, Target.cs, CastSpell.cs.
|
||||
- Serialization:
|
||||
- PacketReader.cs and PacketWriter.cs provide low-level read/write utilities.
|
||||
|
||||
Integration points:
|
||||
- Register custom incoming/outgoing handlers at engine startup.
|
||||
- Apply filters to reduce noise or enforce security policies.
|
||||
- Enqueue actions to avoid race conditions during high-frequency operations.
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [UseSkill.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseSkill.cs)
|
||||
- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [PacketReader.cs](file://ClassicAssist.Shared/UO/Data/PacketReader.cs)
|
||||
- [PacketWriter.cs](file://ClassicAssist.Shared/UO/Data/PacketWriter.cs)
|
||||
|
||||
### UI API (Cross-Platform Interface Operations)
|
||||
- Dispatcher:
|
||||
- AvaloniaDispatcher.cs implements IDispatcher for Avalonia.
|
||||
- UI Invoker:
|
||||
- AvaloniaUIInvoker.cs implements IUIInvoker for platform-specific UI calls.
|
||||
- Usage:
|
||||
- Marshal UI updates onto the UI thread safely.
|
||||
- Show dialogs, update controls, and manage windows using the invoker.
|
||||
|
||||
Thread safety:
|
||||
- Always use the dispatcher to update UI state from non-UI threads.
|
||||
- Avoid direct UI manipulation outside the UI thread.
|
||||
|
||||
**Section sources**
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The architecture separates platform-specific UI concerns from shared core logic. The Avalonia project provides the UI layer and integrates with the shared engine, which coordinates networking, macros, hotkeys, and object models.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as "Avalonia App"
|
||||
participant Engine as "Shared Engine"
|
||||
participant NetIn as "IncomingPacketHandlers"
|
||||
participant NetOut as "OutgoingPacketHandlers"
|
||||
participant Queue as "ActionPacketQueue"
|
||||
participant UI as "AvaloniaDispatcher / IUIInvoker"
|
||||
App->>Engine : Initialize()
|
||||
Engine->>NetIn : Register handlers
|
||||
Engine->>NetOut : Register handlers
|
||||
Engine->>Queue : Configure queue
|
||||
Engine->>UI : Set up dispatcher and invoker
|
||||
Note over Engine,NetIn : Incoming packets flow through filters and handlers
|
||||
Note over Engine,NetOut : Outgoing actions are queued and dispatched
|
||||
Note over Engine,UI : UI updates are marshaled to the UI thread
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Engine API Deep Dive
|
||||
- Initialization sequence:
|
||||
- Program.cs bootstraps Avalonia and invokes Engine initialization.
|
||||
- App.axaml.cs loads resources and sets up services.
|
||||
- Engine.cs wires up network handlers, macro manager, and UI infrastructure.
|
||||
- Dispatcher and UI invoker:
|
||||
- IDispatcher abstracts cross-thread execution.
|
||||
- IUIInvoker encapsulates platform-specific UI operations.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Engine {
|
||||
+Initialize()
|
||||
+Start()
|
||||
+Stop()
|
||||
+RegisterIncomingHandler(type, handler)
|
||||
+RegisterOutgoingHandler(type, handler)
|
||||
+EnqueueAction(action)
|
||||
+GetDispatcher()
|
||||
+GetUIInvoker()
|
||||
}
|
||||
class IDispatcher {
|
||||
<<interface>>
|
||||
+InvokeOnUiThread(callback)
|
||||
+BeginInvokeOnUiThread(callback)
|
||||
}
|
||||
class IUIInvoker {
|
||||
<<interface>>
|
||||
+ShowDialog(title, message)
|
||||
+UpdateControl(control, action)
|
||||
}
|
||||
class AvaloniaDispatcher {
|
||||
+InvokeOnUiThread(callback)
|
||||
+BeginInvokeOnUiThread(callback)
|
||||
}
|
||||
class AvaloniaUIInvoker {
|
||||
+ShowDialog(title, message)
|
||||
+UpdateControl(control, action)
|
||||
}
|
||||
Engine --> IDispatcher : "uses"
|
||||
Engine --> IUIInvoker : "uses"
|
||||
AvaloniaDispatcher ..|> IDispatcher
|
||||
AvaloniaUIInvoker ..|> IUIInvoker
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
### Network API Deep Dive
|
||||
- Incoming packet flow:
|
||||
- Server sends packet -> Filter chain evaluates -> Handler processes -> State updates
|
||||
- Outgoing packet flow:
|
||||
- Client action -> Enqueued -> Serialized -> Sent via writer
|
||||
- Packet type hierarchy:
|
||||
- BasePacket defines common fields and serialization helpers
|
||||
- Specific packets extend base and implement type-specific logic
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Incoming Packet Received"]) --> Filter["Apply Filters"]
|
||||
Filter --> Filtered{"Filtered?"}
|
||||
Filtered --> |Yes| Drop["Drop Packet"]
|
||||
Filtered --> |No| Route["Route to Handler"]
|
||||
Route --> Handle["Execute Handler Logic"]
|
||||
Handle --> UpdateState["Update Game State"]
|
||||
UpdateState --> End(["Done"])
|
||||
Drop --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [UseSkill.cs](file://ClassicAssist.Shared/UO/Network/Packets/UseSkill.cs)
|
||||
- [Target.cs](file://ClassicAssist.Shared/UO/Network/Packets/Target.cs)
|
||||
- [CastSpell.cs](file://ClassicAssist.Shared/UO/Network/Packets/CastSpell.cs)
|
||||
- [PacketReader.cs](file://ClassicAssist.Shared/UO/Data/PacketReader.cs)
|
||||
- [PacketWriter.cs](file://ClassicAssist.Shared/UO/Data/PacketWriter.cs)
|
||||
|
||||
### Macro Command Reference
|
||||
The macro system exposes a rich set of commands grouped by domain. Each command typically follows a consistent signature pattern:
|
||||
- Method name: VerbNoun (e.g., MoveTo, Attack, Say)
|
||||
- Parameters: Typed arguments describing targets, coordinates, messages, etc.
|
||||
- Return value: Boolean indicating success/failure or status codes
|
||||
- Side effects: May send network packets, update state, or trigger UI updates
|
||||
|
||||
Key command groups:
|
||||
- MainCommands.cs: Core engine interactions
|
||||
- ActionCommands.cs: General actions (attack, move, target)
|
||||
- AgentCommands.cs: Agent control and queries
|
||||
- EntityCommands.cs: Entity inspection and manipulation
|
||||
- GumpCommands.cs: Gump interaction
|
||||
- JournalCommands.cs: Journal entries and history
|
||||
- ListCommands.cs: Collection operations
|
||||
- MobileCommands.cs: Mobile-specific actions
|
||||
- MovementCommands.cs: Navigation and positioning
|
||||
- MsgCommands.cs: Messaging and chat
|
||||
- ObjectCommands.cs: Item and object operations
|
||||
- PropertiesCommands.cs: Property access and modification
|
||||
- RegionCommands.cs: Region queries and checks
|
||||
- SkillCommands.cs: Skill-related operations
|
||||
- SpellCommands.cs: Spell casting and management
|
||||
- TargetCommands.cs: Targeting operations
|
||||
- TimerCommands.cs: Timers and scheduling
|
||||
- WandCommands.cs: Wand item interactions
|
||||
|
||||
Example usage patterns:
|
||||
- Conditional branching based on entity properties
|
||||
- Looping over collections with list commands
|
||||
- Asynchronous timers for delayed actions
|
||||
- Error handling via return values and journal logs
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [MainCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MainCommands.cs)
|
||||
- [ActionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ActionCommands.cs)
|
||||
- [AgentCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/AgentCommands.cs)
|
||||
- [EntityCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/EntityCommands.cs)
|
||||
- [GumpCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/GumpCommands.cs)
|
||||
- [JournalCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/JournalCommands.cs)
|
||||
- [ListCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ListCommands.cs)
|
||||
- [MobileCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MobileCommands.cs)
|
||||
- [MovementCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MovementCommands.cs)
|
||||
- [MsgCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/MsgCommands.cs)
|
||||
- [ObjectCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/ObjectCommands.cs)
|
||||
- [PropertiesCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/PropertiesCommands.cs)
|
||||
- [RegionCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/RegionCommands.cs)
|
||||
- [SkillCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SkillCommands.cs)
|
||||
- [SpellCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/SpellCommands.cs)
|
||||
- [TargetCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TargetCommands.cs)
|
||||
- [TimerCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/TimerCommands.cs)
|
||||
- [WandCommands.cs](file://ClassicAssist.Shared/Data/Macros/Commands/WandCommands.cs)
|
||||
|
||||
### Extension Points
|
||||
- Plugin interfaces:
|
||||
- HotkeyCommandAttribute.cs allows registering hotkey-bound commands
|
||||
- IConfigurableFilter.cs enables customizable filter implementations
|
||||
- FilterOptionsAttribute.cs provides metadata for filter configuration
|
||||
- Event hooks:
|
||||
- Incoming and outgoing packet handlers serve as event hooks for network events
|
||||
- Macro invoker exposes hooks for macro execution lifecycle
|
||||
- Configuration options:
|
||||
- AssistantOptions.cs and Options.cs define configurable settings
|
||||
- OptionsBindingAttribute.cs supports binding options to UI
|
||||
|
||||
Best practices:
|
||||
- Implement IConfigurableFilter to add new filtering logic
|
||||
- Use HotkeyCommandAttribute to expose commands via hotkeys
|
||||
- Leverage filter options for user-configurable parameters
|
||||
|
||||
**Section sources**
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
### Data Models and Relationships
|
||||
Core UO object model:
|
||||
- Entity is the base class for all in-game entities
|
||||
- Item extends Entity for items and containers
|
||||
- Mobile extends Entity for living beings
|
||||
- PlayerMobile extends Mobile for the local player
|
||||
- Gump represents UI elements
|
||||
- Menu represents interactive menus
|
||||
- Property represents dynamic properties on entities
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Entity {
|
||||
+int Serial
|
||||
+int Hue
|
||||
+string Name
|
||||
+bool IsValid()
|
||||
+GetProperty(name) Property
|
||||
}
|
||||
class Item {
|
||||
+int Layer
|
||||
+int Amount
|
||||
+bool IsContainer()
|
||||
+GetContents() IEnumerable~Item~
|
||||
}
|
||||
class Mobile {
|
||||
+int HP
|
||||
+int MaxHP
|
||||
+int Mana
|
||||
+int MaxMana
|
||||
+bool IsDead()
|
||||
+bool IsAlive()
|
||||
}
|
||||
class PlayerMobile {
|
||||
+int Gold
|
||||
+int Stamina
|
||||
+int MaxStamina
|
||||
+bool IsPlayer()
|
||||
}
|
||||
class Gump {
|
||||
+int GumpId
|
||||
+string Title
|
||||
+IEnumerable~Button~ Buttons
|
||||
}
|
||||
class Menu {
|
||||
+int MenuId
|
||||
+string Title
|
||||
+IEnumerable~MenuItem~ Items
|
||||
}
|
||||
class Property {
|
||||
+string Name
|
||||
+string Value
|
||||
+Type ValueType
|
||||
}
|
||||
Entity <|-- Item
|
||||
Entity <|-- Mobile
|
||||
Mobile <|-- PlayerMobile
|
||||
Gump --> Property : "contains"
|
||||
Menu --> Property : "uses"
|
||||
```
|
||||
|
||||
**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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
- [Menu.cs](file://ClassicAssist.Shared/UO/Objects/Menu.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
Validation rules:
|
||||
- Entity validity checks ensure safe access to properties
|
||||
- Mobile health and mana ranges are validated before operations
|
||||
- Item container operations verify capacity and permissions
|
||||
|
||||
**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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Gump.cs](file://ClassicAssist.Shared/UO/Objects/Gumps/Gump.cs)
|
||||
- [Menu.cs](file://ClassicAssist.Shared/UO/Objects/Menu.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram illustrates key dependencies between major components:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Engine["Engine.cs"] --> IDispatcher["IDispatcher.cs"]
|
||||
Engine --> IUIInvoker["IUIInvoker.cs"]
|
||||
Engine --> MacroManager["MacroManager.cs"]
|
||||
Engine --> IncomingPacketHandlers["IncomingPacketHandlers.cs"]
|
||||
Engine --> OutgoingPacketHandlers["OutgoingPacketHandlers.cs"]
|
||||
Engine --> IncomingPacketFilters["IncomingPacketFilters.cs"]
|
||||
Engine --> ActionPacketQueue["ActionPacketQueue.cs"]
|
||||
IncomingPacketHandlers --> BasePacket["BasePacket.cs"]
|
||||
OutgoingPacketHandlers --> BasePacket
|
||||
IncomingPacketFilters --> BasePacket
|
||||
MacroManager --> MacroInvoker["MacroInvoker.cs"]
|
||||
MacroInvoker --> MacroEntry["MacroEntry.cs"]
|
||||
AvaloniaDispatcher["AvaloniaDispatcher.cs"] --> IDispatcher
|
||||
AvaloniaUIInvoker["AvaloniaUIInvoker.cs"] --> IUIInvoker
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [IDispatcher.cs](file://ClassicAssist.Shared/IDispatcher.cs)
|
||||
- [IUIInvoker.cs](file://ClassicAssist.Shared/IUIInvoker.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Shared/Engine.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs)
|
||||
- [OutgoingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketHandlers.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [ActionPacketQueue.cs](file://ClassicAssist.Shared/UO/Network/ActionPacketQueue.cs)
|
||||
- [BasePacket.cs](file://ClassicAssist.Shared/UO/Network/Packets/BasePacket.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Network efficiency:
|
||||
- Use packet filters to reduce processing overhead
|
||||
- Batch operations where possible to minimize network traffic
|
||||
- Avoid excessive logging in hot paths
|
||||
- Threading model:
|
||||
- Keep UI updates on the UI thread using the dispatcher
|
||||
- Process network packets off the UI thread to maintain responsiveness
|
||||
- Use the action queue to serialize time-sensitive operations
|
||||
- Memory management:
|
||||
- Reuse packet readers/writers when possible
|
||||
- Clean up large collections and dispose of resources appropriately
|
||||
- Monitor memory usage during long-running macros
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- UI not updating:
|
||||
- Ensure UI updates are dispatched to the UI thread
|
||||
- Verify the dispatcher is properly initialized
|
||||
- Packet handling errors:
|
||||
- Check filter configurations for overly restrictive rules
|
||||
- Validate packet type registrations match server expectations
|
||||
- Macro execution failures:
|
||||
- Review command syntax and parameter types
|
||||
- Check return values for error conditions
|
||||
- Examine journal logs for detailed error information
|
||||
|
||||
Debugging tips:
|
||||
- Enable verbose logging for network packets
|
||||
- Use the object inspector to examine entity states
|
||||
- Test macros in isolation to identify problematic commands
|
||||
|
||||
**Section sources**
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
## Conclusion
|
||||
ClassicAssist.Avalonia provides a robust framework for extending Ultima Online gameplay through well-defined APIs. The separation of concerns between UI, networking, and core logic enables flexible integration while maintaining performance and reliability. By following the documented patterns and best practices, developers can create powerful automation tools and enhancements that integrate seamlessly with the game client.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Version Compatibility and Migration
|
||||
- API stability:
|
||||
- Public interfaces are designed for backward compatibility
|
||||
- Breaking changes are documented with migration guides
|
||||
- Deprecation notices:
|
||||
- Deprecated features are marked with attributes and documentation
|
||||
- Migration timelines are provided for significant changes
|
||||
- Upgrade procedures:
|
||||
- Follow step-by-step migration guides for major version upgrades
|
||||
- Test extensions thoroughly after upgrading dependencies
|
||||
|
||||
### Code Examples and Integration Scenarios
|
||||
- Basic engine initialization:
|
||||
- Initialize the engine in your application startup
|
||||
- Register custom packet handlers and filters
|
||||
- Set up the dispatcher and UI invoker
|
||||
- Custom packet handler:
|
||||
- Implement incoming packet handler interface
|
||||
- Parse packet data using the reader
|
||||
- Update game state and notify subscribers
|
||||
- Macro development:
|
||||
- Create custom macro commands using attributes
|
||||
- Implement complex logic with conditional statements
|
||||
- Use timers for asynchronous operations
|
||||
- UI integration:
|
||||
- Use the dispatcher for cross-thread UI updates
|
||||
- Implement custom controls using the UI invoker
|
||||
- Bind data to UI elements using MVVM patterns
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
@@ -0,0 +1,340 @@
|
||||
# Core APIs
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.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 provides comprehensive API documentation for ClassicAssist.Avalonia’s core application interfaces, focusing on:
|
||||
- Engine class for application lifecycle management, initialization, and shutdown procedures
|
||||
- Commands API for game command execution and routing
|
||||
- BaseViewModel for property binding, event handling, and MVVM pattern implementation
|
||||
- ExtensionMethods utility classes with helper functions and common operations
|
||||
|
||||
The goal is to help developers integrate and consume these APIs safely, understand thread-safety considerations, performance implications, and best practices.
|
||||
|
||||
## Project Structure
|
||||
At a high level, the Avalonia-based application entry points initialize the UI framework and start the Engine. Shared components (commands, view models, utilities) live in ClassicAssist.Shared and are consumed by both WPF and Avalonia implementations. The following diagram shows the key files involved in startup and core APIs.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Program["Program.cs"] --> App["App.axaml.cs"]
|
||||
App --> EngineAvalonia["Engine.cs (Avalonia)"]
|
||||
EngineAvalonia --> Dispatcher["AvaloniaDispatcher.cs"]
|
||||
EngineAvalonia --> UIInvoker["AvaloniaUIInvoker.cs"]
|
||||
EngineAvalonia --> CommandsShared["CommandsManager.cs (Shared)"]
|
||||
EngineAvalonia --> BaseVM["BaseViewModel.cs (Shared)"]
|
||||
EngineAvalonia --> ExtWPF["ExtensionMethods.cs (WPF)"]
|
||||
EngineAvalonia --> ExtShared["ExtensionMethods.cs (Shared)"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
|
||||
## Core Components
|
||||
- Engine (Avalonia): Orchestrates application lifecycle, initializes subsystems, manages dispatching to UI threads, and coordinates shutdown.
|
||||
- Commands API (Shared): Centralized command registration, discovery, parsing, and execution pipeline.
|
||||
- BaseViewModel (Shared): MVVM base class providing property change notification, safe UI-thread updates, and common helpers.
|
||||
- ExtensionMethods (WPF and Shared): Utility extensions for common operations used across the codebase.
|
||||
|
||||
Key responsibilities:
|
||||
- Engine: bootstrap, configuration, service resolution, dispatcher integration, graceful shutdown
|
||||
- Commands: attribute-driven or programmatic command registration, parameter parsing, invocation
|
||||
- BaseViewModel: INotifyPropertyChanged-like behavior, thread-safe property updates, convenience methods
|
||||
- Extensions: string, collection, object, and UI-related helpers
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The Avalonia application starts via Program, which bootstraps App. App initializes the Engine, which sets up the dispatcher and UI invoker, registers commands, and prepares the UI. ViewModels inherit from BaseViewModel to bind properties and handle events. Utilities in ExtensionMethods support common tasks throughout the app.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant OS as "Operating System"
|
||||
participant Program as "Program.cs"
|
||||
participant App as "App.axaml.cs"
|
||||
participant Engine as "Engine.cs (Avalonia)"
|
||||
participant Dispatcher as "AvaloniaDispatcher.cs"
|
||||
participant UIInvoker as "AvaloniaUIInvoker.cs"
|
||||
participant Commands as "CommandsManager.cs"
|
||||
participant VM as "BaseViewModel.cs"
|
||||
OS->>Program : Launch process
|
||||
Program->>App : Create and configure App
|
||||
App->>Engine : Initialize()
|
||||
Engine->>Dispatcher : Set up dispatcher
|
||||
Engine->>UIInvoker : Configure UI invoker
|
||||
Engine->>Commands : Register commands
|
||||
Engine-->>App : Ready
|
||||
App-->>OS : Run message loop
|
||||
VM->>VM : Property changes notify UI
|
||||
Commands->>Commands : Parse and execute commands
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Engine (Avalonia)
|
||||
Responsibilities:
|
||||
- Application lifecycle: initialization, readiness signaling, shutdown
|
||||
- Dispatcher integration: ensures UI updates occur on the correct thread
|
||||
- UI invoker: abstracts UI-specific invoke semantics
|
||||
- Command system integration: registers and exposes command execution facilities
|
||||
- Resource and subsystem coordination: optional services and managers
|
||||
|
||||
Typical usage patterns:
|
||||
- Call initialization during app startup
|
||||
- Use provided dispatcher/invoker to marshal work to UI thread
|
||||
- Invoke commands through the centralized manager
|
||||
- Perform cleanup on shutdown
|
||||
|
||||
Thread safety:
|
||||
- All UI-bound operations should be dispatched via the configured dispatcher/invoker
|
||||
- Avoid direct cross-thread UI access; rely on Engine-provided abstractions
|
||||
|
||||
Error handling:
|
||||
- Initialization failures should be surfaced early to allow graceful degradation
|
||||
- Shutdown should release resources and stop background work
|
||||
|
||||
Best practices:
|
||||
- Keep initialization lightweight; defer heavy work until needed
|
||||
- Centralize error logging and user-facing messages via shared providers
|
||||
- Ensure deterministic shutdown order to avoid race conditions
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
|
||||
### Commands API (CommandsManager)
|
||||
Responsibilities:
|
||||
- Command registration (attribute-driven or programmatic)
|
||||
- Command discovery and metadata storage
|
||||
- Parameter parsing and validation
|
||||
- Execution pipeline with context and result handling
|
||||
- Routing to appropriate handlers
|
||||
|
||||
Method categories:
|
||||
- Registration: add commands, aliases, and metadata
|
||||
- Resolution: find commands by name or alias
|
||||
- Invocation: parse input and execute target handler
|
||||
- Enumeration: list available commands and help info
|
||||
|
||||
Usage examples:
|
||||
- Register a command once during engine initialization
|
||||
- Execute commands from macros, hotkeys, or UI actions
|
||||
- Provide help text and parameter descriptions for discoverability
|
||||
|
||||
Exception handling:
|
||||
- Validate parameters before execution
|
||||
- Wrap handler exceptions to prevent crashes and provide meaningful errors
|
||||
- Return structured results for callers to interpret
|
||||
|
||||
Thread safety:
|
||||
- Command registration typically occurs on the main thread
|
||||
- Execution may be invoked from various threads; ensure handlers use dispatcher when touching UI state
|
||||
|
||||
Performance:
|
||||
- Cache resolved command references where possible
|
||||
- Minimize allocations in hot paths (parsing, argument splitting)
|
||||
|
||||
**Section sources**
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
|
||||
### BaseViewModel
|
||||
Responsibilities:
|
||||
- Property change notification for data binding
|
||||
- Safe UI-thread updates for bound properties
|
||||
- Event handling helpers and subscription management
|
||||
- Common MVVM utilities (e.g., can-execute flags, command wrappers)
|
||||
|
||||
Property binding:
|
||||
- Implement change notifications consistently
|
||||
- Prefer computed properties for derived values
|
||||
- Avoid heavy logic in property getters/setters
|
||||
|
||||
Event handling:
|
||||
- Subscribe/unsubscribe events safely
|
||||
- Use weak references or explicit unsubscription to prevent leaks
|
||||
|
||||
MVVM pattern:
|
||||
- Keep UI logic out of views; encapsulate in ViewModels
|
||||
- Expose commands and observable collections for binding
|
||||
|
||||
Thread safety:
|
||||
- Always update bound properties on the UI thread using the provided dispatcher/invoker
|
||||
- Guard against concurrent modifications to collections exposed to UI
|
||||
|
||||
Best practices:
|
||||
- Keep ViewModels lightweight and testable
|
||||
- Use dependency injection for services
|
||||
- Avoid direct UI framework dependencies in shared ViewModels
|
||||
|
||||
**Section sources**
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
|
||||
### ExtensionMethods (Utilities)
|
||||
Two primary locations:
|
||||
- WPF-specific extensions (ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- Shared extensions (ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
Common categories:
|
||||
- String utilities: trimming, formatting, null-safe operations
|
||||
- Collection helpers: filtering, mapping, batching
|
||||
- Object utilities: casting, null checks, defaulting
|
||||
- UI helpers: dispatcher calls, resource lookups (platform-specific)
|
||||
|
||||
Usage guidance:
|
||||
- Prefer shared extensions for cross-platform compatibility
|
||||
- Use WPF-specific extensions only within WPF projects
|
||||
- Keep extension methods small and focused
|
||||
|
||||
Performance:
|
||||
- Avoid unnecessary allocations in frequently called helpers
|
||||
- Be mindful of LINQ overhead in tight loops
|
||||
|
||||
**Section sources**
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
The following diagram highlights key dependencies among core components.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Program {
|
||||
+Main()
|
||||
}
|
||||
class App {
|
||||
+Initialize()
|
||||
+Run()
|
||||
}
|
||||
class Engine {
|
||||
+Initialize()
|
||||
+Shutdown()
|
||||
+DispatchToUI(action)
|
||||
+InvokeUI(action)
|
||||
}
|
||||
class AvaloniaDispatcher {
|
||||
+BeginInvoke(action)
|
||||
+Invoke(action)
|
||||
}
|
||||
class AvaloniaUIInvoker {
|
||||
+Invoke(action)
|
||||
}
|
||||
class CommandsManager {
|
||||
+Register(command)
|
||||
+Execute(input)
|
||||
+Resolve(name)
|
||||
}
|
||||
class BaseViewModel {
|
||||
+NotifyPropertyChanged(propertyName)
|
||||
+UpdateOnUIThread(action)
|
||||
}
|
||||
class ExtensionMethods_WPF
|
||||
class ExtensionMethods_Shared
|
||||
Program --> App : "creates"
|
||||
App --> Engine : "initializes"
|
||||
Engine --> AvaloniaDispatcher : "uses"
|
||||
Engine --> AvaloniaUIInvoker : "uses"
|
||||
Engine --> CommandsManager : "registers/executes"
|
||||
Engine --> BaseViewModel : "consumes"
|
||||
Engine --> ExtensionMethods_Shared : "uses"
|
||||
Engine --> ExtensionMethods_WPF : "uses (WPF project)"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist/Misc/ExtensionMethods.cs)
|
||||
- [ExtensionMethods.cs](file://ClassicAssist.Shared/Misc/ExtensionMethods.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Minimize UI thread work: offload heavy computations to background threads and marshal results back to UI via dispatcher/invoker
|
||||
- Batch UI updates: coalesce multiple property changes to reduce layout passes
|
||||
- Avoid excessive allocations: reuse buffers and objects in hot paths
|
||||
- Lazy initialization: defer expensive setup until first use
|
||||
- Efficient command parsing: cache parsed structures when inputs repeat
|
||||
- Careful event subscription: unsubscribe promptly to prevent memory leaks
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Cross-thread UI access: always use dispatcher/invoker to update UI-bound properties
|
||||
- Command not found: verify registration order and ensure names/aliases match exactly
|
||||
- Exceptions in command handlers: wrap handler calls and log detailed context
|
||||
- Memory leaks: ensure event subscriptions are disposed and long-lived references are released
|
||||
- Startup failures: check initialization sequence and external dependencies availability
|
||||
|
||||
Operational tips:
|
||||
- Enable verbose logging during development
|
||||
- Add unit tests for command handlers and ViewModel logic
|
||||
- Use profiling tools to identify bottlenecks in UI updates and command execution
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [CommandsManager.cs](file://ClassicAssist.Shared/Data/Commands/CommandsManager.cs)
|
||||
- [BaseViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/BaseViewModel.cs)
|
||||
|
||||
## Conclusion
|
||||
The core APIs of ClassicAssist.Avalonia center around a robust Engine that orchestrates lifecycle and threading, a flexible Commands API for extensible command execution, a solid BaseViewModel foundation for MVVM, and practical ExtensionMethods utilities. By adhering to thread-safety guidelines, leveraging dispatcher/invoker abstractions, and following best practices for performance and error handling, developers can build reliable and responsive features atop these interfaces.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
@@ -0,0 +1,474 @@
|
||||
# Data Models
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.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 describes the core data models used by ClassicAssist.Avalonia, focusing on game entities and configuration objects. It covers the Entity hierarchy (Entity base class, Mobile for living creatures, Item for game objects), scripting storage via MacroEntry, and key binding configuration via HotkeyEntry. For each model, we define fields, types, validation rules, serialization formats, relationships, lifecycle methods, access patterns, caching strategies, performance considerations, migration paths, version compatibility, and backup/restore procedures.
|
||||
|
||||
## Project Structure
|
||||
The relevant data models are primarily located under:
|
||||
- Game entities: ClassicAssist.Shared/UO/Objects
|
||||
- Configuration and macros: ClassicAssist.Shared/Data/Macros and ClassicAssist.Shared/Data/Hotkeys
|
||||
- Global options: ClassicAssist.Shared/Data
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Game Objects"
|
||||
E["Entity"]
|
||||
M["Mobile"]
|
||||
I["Item"]
|
||||
PM["PlayerMobile"]
|
||||
P["Property"]
|
||||
end
|
||||
subgraph "Configuration"
|
||||
ME["MacroEntry"]
|
||||
HE["HotkeyEntry"]
|
||||
OPT["Options"]
|
||||
AO["AssistantOptions"]
|
||||
end
|
||||
E --> M
|
||||
E --> I
|
||||
M --> PM
|
||||
I --> P
|
||||
OPT --> ME
|
||||
OPT --> HE
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual structure]
|
||||
|
||||
## Core Components
|
||||
- Entity: Base type for all in-game objects with identity, location, and state.
|
||||
- Mobile: Living entity extending Entity with movement, combat, and status attributes.
|
||||
- Item: Inanimate object extending Entity with container semantics and properties.
|
||||
- PlayerMobile: Specialized Mobile representing the local player.
|
||||
- Property: Key-value pair attached to Items.
|
||||
- MacroEntry: Script definition and metadata for macro execution.
|
||||
- HotkeyEntry: Key binding configuration mapping keys to commands.
|
||||
- Options and AssistantOptions: Application-level settings containers.
|
||||
|
||||
Key responsibilities:
|
||||
- Identity and lifetime management for entities.
|
||||
- Composition of properties for items.
|
||||
- Storage and invocation of macro scripts.
|
||||
- Binding hotkeys to commands.
|
||||
- Centralized application configuration.
|
||||
|
||||
**Section sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The data model follows a clear inheritance hierarchy for game objects and a composition pattern for configuration and scripting. Entities form a tree-like world model where Items can contain other Items and hold Properties. Macros and hotkeys are persisted as part of application options.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Entity {
|
||||
+int Serial
|
||||
+string Name
|
||||
+int Hue
|
||||
+int X
|
||||
+int Y
|
||||
+int Z
|
||||
+int Map
|
||||
+bool Visible
|
||||
+bool Deleted
|
||||
+void Update()
|
||||
+void Dispose()
|
||||
}
|
||||
class Mobile {
|
||||
+int Body
|
||||
+int Stamina
|
||||
+int Mana
|
||||
+int Hits
|
||||
+bool IsDead
|
||||
+void MoveTo(x,y,z)
|
||||
+void Attack(target)
|
||||
}
|
||||
class Item {
|
||||
+int Amount
|
||||
+int Layer
|
||||
+Property[] Properties
|
||||
+void AddProperty(key,value)
|
||||
+void RemoveProperty(key)
|
||||
}
|
||||
class PlayerMobile {
|
||||
+bool IsLocalPlayer
|
||||
+void CastSpell(spellId)
|
||||
}
|
||||
class Property {
|
||||
+string Key
|
||||
+string Value
|
||||
}
|
||||
class MacroEntry {
|
||||
+string Name
|
||||
+string Category
|
||||
+string Script
|
||||
+bool Enabled
|
||||
+void Execute()
|
||||
}
|
||||
class HotkeyEntry {
|
||||
+string Command
|
||||
+string Keys
|
||||
+bool Enabled
|
||||
+void Bind()
|
||||
+void Unbind()
|
||||
}
|
||||
class Options {
|
||||
+MacroEntry[] Macros
|
||||
+HotkeyEntry[] Hotkeys
|
||||
+void Save()
|
||||
+void Load()
|
||||
}
|
||||
class AssistantOptions {
|
||||
+string Language
|
||||
+bool EnableDebug
|
||||
+void Apply()
|
||||
}
|
||||
Entity <|-- Mobile
|
||||
Entity <|-- Item
|
||||
Mobile <|-- PlayerMobile
|
||||
Item --> Property : "has many"
|
||||
Options --> MacroEntry : "contains"
|
||||
Options --> HotkeyEntry : "contains"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Entity Hierarchy
|
||||
- Entity
|
||||
- Purpose: Base representation of any in-world object.
|
||||
- Key fields: serial identifier, name, hue, coordinates (X, Y, Z), map, visibility flags, deletion state.
|
||||
- Lifecycle: creation upon packet processing, update on incoming updates, disposal when removed.
|
||||
- Methods: update hooks, disposal/cleanup.
|
||||
- Mobile
|
||||
- Extends Entity; represents living creatures.
|
||||
- Additional fields: body type, stamina, mana, hits, death state.
|
||||
- Methods: movement, attack, status updates.
|
||||
- Item
|
||||
- Extends Entity; represents inanimate objects.
|
||||
- Additional fields: amount, layer, collection of Property entries.
|
||||
- Methods: property management, container operations.
|
||||
- PlayerMobile
|
||||
- Specialization of Mobile for the local player.
|
||||
- Additional behavior: spell casting, local-only flags.
|
||||
|
||||
Validation rules:
|
||||
- Coordinates within valid ranges per map.
|
||||
- Non-negative amounts for Items.
|
||||
- Valid hues and body IDs.
|
||||
|
||||
Serialization format:
|
||||
- Typically serialized via binary packets from the game client; persistence uses JSON/XML through Options.
|
||||
|
||||
Relationships:
|
||||
- Items may contain other Items (container hierarchy).
|
||||
- Items have zero or more Properties.
|
||||
|
||||
Lifecycle methods:
|
||||
- OnCreate: initialize defaults.
|
||||
- OnUpdate: apply incremental changes.
|
||||
- OnRemove: cleanup resources and references.
|
||||
|
||||
Data access patterns:
|
||||
- Use collections to query by serial, name, or filters.
|
||||
- Cache frequently accessed entities to reduce lookup overhead.
|
||||
|
||||
Caching strategies:
|
||||
- Maintain an in-memory index keyed by serial.
|
||||
- Invalidate cache on removal or significant updates.
|
||||
|
||||
Performance considerations:
|
||||
- Avoid deep traversals during hot loops; prefer indexed lookups.
|
||||
- Batch updates to minimize UI refreshes.
|
||||
|
||||
Migration and compatibility:
|
||||
- Introduce versioned schema for new fields; provide default values for older versions.
|
||||
- Validate and normalize legacy data on load.
|
||||
|
||||
Backup/restore:
|
||||
- Export entity snapshots for debugging; restore only in controlled environments.
|
||||
|
||||
**Section sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
|
||||
#### Class Diagram: Entity Hierarchy
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Entity
|
||||
class Mobile
|
||||
class Item
|
||||
class PlayerMobile
|
||||
class Property
|
||||
Entity <|-- Mobile
|
||||
Entity <|-- Item
|
||||
Mobile <|-- PlayerMobile
|
||||
Item --> Property
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
|
||||
### Property Model
|
||||
- Purpose: Attach arbitrary key-value metadata to Items.
|
||||
- Fields: key (string), value (string).
|
||||
- Validation: unique keys per Item; non-empty key.
|
||||
- Serialization: embedded in Item’s serialized form.
|
||||
- Access patterns: dictionary-style lookup by key; iterate for bulk operations.
|
||||
|
||||
**Section sources**
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [Item.cs](file://ClassicAssist.Shared/UO/Objects/Item.cs)
|
||||
|
||||
### MacroEntry
|
||||
- Purpose: Store macro script definitions and metadata.
|
||||
- Fields: name, category, script content, enabled flag.
|
||||
- Validation: non-empty name; script syntax checked at runtime.
|
||||
- Serialization: stored within Options as a list of MacroEntry.
|
||||
- Execution: invoked via MacroManager; supports parameters and command context.
|
||||
|
||||
Access patterns:
|
||||
- List-based enumeration for UI.
|
||||
- Filter by category or enabled state.
|
||||
|
||||
Caching:
|
||||
- Pre-parse and cache compiled representations if applicable.
|
||||
|
||||
Performance:
|
||||
- Avoid heavy parsing on every execution; cache parsed forms.
|
||||
|
||||
Migration:
|
||||
- Version macro schemas; provide converters for old formats.
|
||||
|
||||
Backup/restore:
|
||||
- Include macros in profile exports; validate on import.
|
||||
|
||||
**Section sources**
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
### HotkeyEntry
|
||||
- Purpose: Define key bindings to commands.
|
||||
- Fields: command string, key combination, enabled flag.
|
||||
- Validation: valid key combination; command exists in registry.
|
||||
- Serialization: stored within Options as a list of HotkeyEntry.
|
||||
- Lifecycle: bind/unbind on enable/disable; persist changes.
|
||||
|
||||
Access patterns:
|
||||
- Lookup by command or key combination.
|
||||
- Iterate to render UI and manage active bindings.
|
||||
|
||||
Caching:
|
||||
- Maintain a map from key combinations to entries for fast dispatch.
|
||||
|
||||
Performance:
|
||||
- Minimize reflection during hot path; resolve commands once.
|
||||
|
||||
Migration:
|
||||
- Normalize legacy key formats; deprecate obsolete commands gracefully.
|
||||
|
||||
Backup/restore:
|
||||
- Export/import hotkeys alongside profiles; warn on conflicts.
|
||||
|
||||
**Section sources**
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
|
||||
### Options and AssistantOptions
|
||||
- Options
|
||||
- Holds global lists of MacroEntry and HotkeyEntry.
|
||||
- Provides Save/Load for persistence.
|
||||
- AssistantOptions
|
||||
- Holds user preferences such as language and debug toggles.
|
||||
- Applies settings at runtime.
|
||||
|
||||
Validation:
|
||||
- Ensure required sections exist; coerce missing fields to defaults.
|
||||
|
||||
Serialization:
|
||||
- JSON or XML depending on platform; consistent across profiles.
|
||||
|
||||
Migration:
|
||||
- Schema versioning with upgraders; backward-compatible reads.
|
||||
|
||||
Backup/restore:
|
||||
- Profile export includes Options and AssistantOptions; integrity checks on import.
|
||||
|
||||
**Section sources**
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
- Entity depends on minimal primitives; Mobile and Item extend it.
|
||||
- Item composes Property instances.
|
||||
- Options aggregates MacroEntry and HotkeyEntry.
|
||||
- AssistantOptions is independent but consumed by Options.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Entity --> Mobile
|
||||
Entity --> Item
|
||||
Mobile --> PlayerMobile
|
||||
Item --> Property
|
||||
Options --> MacroEntry
|
||||
Options --> HotkeyEntry
|
||||
Options --> AssistantOptions
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
**Section sources**
|
||||
- [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)
|
||||
- [PlayerMobile.cs](file://ClassicAssist.Shared/UO/Objects/PlayerMobile.cs)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Prefer indexed lookups over linear scans for large entity sets.
|
||||
- Batch UI updates to avoid excessive redraws.
|
||||
- Cache parsed macro scripts and resolved hotkey commands.
|
||||
- Avoid deep recursion when traversing item containers; use iterative approaches.
|
||||
- Use lightweight DTOs for serialization to reduce allocations.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Missing fields after upgrade: ensure default values are applied during load.
|
||||
- Invalid key combinations: validate and prompt user to rebind.
|
||||
- Macro execution errors: check script syntax and available commands.
|
||||
- Entity not found: verify serial validity and presence in current map.
|
||||
|
||||
Operational checks:
|
||||
- Validate Options schema before applying.
|
||||
- Log warnings for deprecated features.
|
||||
- Provide rollback on failed imports.
|
||||
|
||||
**Section sources**
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
|
||||
## Conclusion
|
||||
The data models in ClassicAssist.Avalonia are organized around a clean Entity hierarchy for game objects and robust configuration structures for macros and hotkeys. By following the recommended access patterns, caching strategies, and migration practices, developers can maintain high performance and reliable upgrades while ensuring user data portability and safety.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Field Definitions Summary
|
||||
- Entity: identity, appearance, position, visibility, lifecycle flags.
|
||||
- Mobile: creature stats and combat-related fields.
|
||||
- Item: quantity, layer, and associated properties.
|
||||
- Property: key-value metadata.
|
||||
- MacroEntry: script metadata and content.
|
||||
- HotkeyEntry: command and key binding.
|
||||
- Options: aggregated configuration lists.
|
||||
- AssistantOptions: user preferences.
|
||||
|
||||
**Section sources**
|
||||
- [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)
|
||||
- [Property.cs](file://ClassicAssist.Shared/UO/Objects/Property.cs)
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [Options.cs](file://ClassicAssist.Shared/Data/Options.cs)
|
||||
- [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs)
|
||||
|
||||
### Data Flow Example: Hotkey Dispatch
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "User"
|
||||
participant OS as "OS Input"
|
||||
participant HK as "HotkeyEntry"
|
||||
participant Cmd as "Command Registry"
|
||||
participant Exec as "Executor"
|
||||
User->>OS : Press key combination
|
||||
OS-->>HK : Key event
|
||||
HK->>Cmd : Resolve command by name
|
||||
Cmd-->>HK : Command handler
|
||||
HK->>Exec : Invoke handler with context
|
||||
Exec-->>User : Action performed
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
|
||||
### Data Flow Example: Macro Execution
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "UI"
|
||||
participant ME as "MacroEntry"
|
||||
participant MM as "MacroManager"
|
||||
participant VM as "VM Context"
|
||||
UI->>ME : Select macro
|
||||
UI->>MM : Execute(ME)
|
||||
MM->>ME : Prepare script
|
||||
MM->>VM : Build execution context
|
||||
MM-->>UI : Result/status
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroEntry.cs](file://ClassicAssist.Shared/Data/Macros/MacroEntry.cs)
|
||||
@@ -0,0 +1,440 @@
|
||||
# Extension Points
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [DynamicFilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/DynamicFilterEntry.cs)
|
||||
- [Filters.cs](file://ClassicAssist.Shared/Engine/Filters.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyCommand.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommand.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
|
||||
- [ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
|
||||
- [MainWindowViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/MainWindowViewModel.cs)
|
||||
- [HotkeysTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/HotkeysTabViewModel.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.xaml.cs)
|
||||
- [RepeatedMessagesFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/RepeatedMessagesFilterConfigureWindow.xaml.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 how to extend ClassicAssist.Avalonia using its extension points. It focuses on:
|
||||
- Filter system interfaces for custom message filters (IConfigurableFilter and FilterEntry)
|
||||
- Hotkey command extension points via HotkeyCommandAttribute
|
||||
- Plugin architecture guidelines including assembly loading, dependency injection, and lifecycle management
|
||||
- Configuration schemas, validation rules, and testing strategies
|
||||
- Security considerations, performance impact, and distribution methods
|
||||
|
||||
The goal is to enable developers to implement custom filters, hotkey commands, and UI extensions that integrate cleanly with the application’s runtime and configuration model.
|
||||
|
||||
## Project Structure
|
||||
The extension points are primarily defined in the shared layer and consumed by the Avalonia UI and launcher components:
|
||||
- Shared filter interfaces and attributes under Data/Filters
|
||||
- Hotkey command attribute and manager under Data/Hotkeys
|
||||
- Packet filtering pipeline under UO/Network
|
||||
- Avalonia app bootstrap and engine initialization under ClassicAssist.Avalonia
|
||||
- Launcher plugin entry and shard management under ClassicAssist.Launcher
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Shared"
|
||||
FIF["IConfigurableFilter.cs"]
|
||||
FE["FilterEntry.cs"]
|
||||
FOA["FilterOptionsAttribute.cs"]
|
||||
HCA["HotkeyCommandAttribute.cs"]
|
||||
HCM["HotkeyManager.cs"]
|
||||
IPF["IncomingPacketFilters.cs"]
|
||||
OPF["OutgoingPacketFilters.cs"]
|
||||
PF["PacketFilter.cs"]
|
||||
end
|
||||
subgraph "Avalonia"
|
||||
APP["App.axaml.cs"]
|
||||
ENG["Engine.cs"]
|
||||
PRG["Program.cs"]
|
||||
CFW["ClilocFilterConfigureWindow.xaml.cs"]
|
||||
RMFW["RepeatedMessagesFilterConfigureWindow.xaml.cs"]
|
||||
end
|
||||
subgraph "Launcher"
|
||||
PLE["PluginEntry.cs"]
|
||||
SM["ShardManager.cs"]
|
||||
end
|
||||
FIF --> FE
|
||||
FOA --> FE
|
||||
HCA --> HCM
|
||||
IPF --> PF
|
||||
OPF --> PF
|
||||
APP --> ENG
|
||||
PRG --> APP
|
||||
PLE --> SM
|
||||
CFW --> FE
|
||||
RMFW --> FE
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
|
||||
- [ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/Views/Filters/ClilocFilterConfigureWindow.xaml.cs)
|
||||
- [RepeatedMessagesFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/RepeatedMessagesFilterConfigureWindow.xaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
|
||||
- [ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
|
||||
|
||||
## Core Components
|
||||
- IConfigurableFilter: Interface for creating custom message filters that can be configured through the UI.
|
||||
- FilterEntry: Base type or container used to represent a filter instance and its configuration state.
|
||||
- FilterOptionsAttribute: Attribute-driven metadata to describe filter options for UI binding and validation.
|
||||
- HotkeyCommandAttribute: Attribute to register a class as a hotkey command, enabling discovery and registration into the hotkey system.
|
||||
- HotkeyManager: Central registry and dispatcher for hotkey commands.
|
||||
- IncomingPacketFilters / OutgoingPacketFilters: Pipeline hooks for intercepting network packets.
|
||||
- PacketFilter: Core packet filtering infrastructure used by incoming/outgoing pipelines.
|
||||
|
||||
These components form the foundation for extending message filtering and keyboard shortcuts.
|
||||
|
||||
**Section sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The extension architecture separates concerns across layers:
|
||||
- Shared layer defines contracts (interfaces, attributes, base types).
|
||||
- Avalonia layer provides UI integration and bootstrapping.
|
||||
- Launcher handles plugin discovery and lifecycle.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Boot as "Program.cs"
|
||||
participant App as "App.axaml.cs"
|
||||
participant Engine as "Engine.cs"
|
||||
participant Filters as "Filters.cs"
|
||||
participant InPkt as "IncomingPacketFilters.cs"
|
||||
participant OutPkt as "OutgoingPacketFilters.cs"
|
||||
participant PktF as "PacketFilter.cs"
|
||||
Boot->>App : Initialize application
|
||||
App->>Engine : Start engine and services
|
||||
Engine->>Filters : Register built-in and discovered filters
|
||||
Engine->>InPkt : Attach incoming packet pipeline
|
||||
Engine->>OutPkt : Attach outgoing packet pipeline
|
||||
InPkt->>PktF : Apply filters to incoming packets
|
||||
OutPkt->>PktF : Apply filters to outgoing packets
|
||||
Note over InPkt,OutPkt : Custom filters implement IConfigurableFilter<br/>and are registered via FilterEntry
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Filters.cs](file://ClassicAssist.Shared/Engine/Filters.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Filter System: IConfigurableFilter and FilterEntry
|
||||
Custom message filters should implement IConfigurableFilter and be represented via FilterEntry. The FilterOptionsAttribute enables declarative configuration UI generation and validation.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IConfigurableFilter {
|
||||
+string Name
|
||||
+bool IsEnabled
|
||||
+void Configure()
|
||||
+bool Evaluate(message) bool
|
||||
}
|
||||
class FilterEntry {
|
||||
+string Id
|
||||
+string Name
|
||||
+bool Enabled
|
||||
+object Options
|
||||
+void Save()
|
||||
+void Load()
|
||||
}
|
||||
class FilterOptionsAttribute {
|
||||
+string DisplayName
|
||||
+string Description
|
||||
+Type ValueType
|
||||
+object DefaultValue
|
||||
}
|
||||
IConfigurableFilter <.. FilterEntry : "implemented by"
|
||||
FilterEntry --> FilterOptionsAttribute : "uses for schema"
|
||||
```
|
||||
|
||||
Key implementation patterns:
|
||||
- Implement IConfigurableFilter to define evaluation logic and configuration behavior.
|
||||
- Use FilterEntry to persist and bind filter state to UI.
|
||||
- Annotate configuration properties with FilterOptionsAttribute to drive UI and validation.
|
||||
|
||||
Example references:
|
||||
- Built-in configurable filters demonstrate usage patterns:
|
||||
- ClilocFilter
|
||||
- RepeatedMessagesFilter
|
||||
|
||||
UI configuration windows:
|
||||
- ClilocFilterConfigureWindow
|
||||
- RepeatedMessagesFilterConfigureWindow
|
||||
|
||||
**Diagram sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.xaml.cs)
|
||||
- [RepeatedMessagesFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/RepeatedMessagesFilterConfigureWindow.xaml.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs)
|
||||
- [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs)
|
||||
- [ClilocFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/ClilocFilterConfigureWindow.xaml.cs)
|
||||
- [RepeatedMessagesFilterConfigureWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/Filters/RepeatedMessagesFilterConfigureWindow.xaml.cs)
|
||||
|
||||
### Hotkey Command Extension Points: HotkeyCommandAttribute
|
||||
To add a new hotkey command:
|
||||
- Decorate your command class with HotkeyCommandAttribute.
|
||||
- Ensure the class adheres to the expected contract recognized by HotkeyManager.
|
||||
- The manager will discover and register the command during startup.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Boot as "Program.cs"
|
||||
participant App as "App.axaml.cs"
|
||||
participant Engine as "Engine.cs"
|
||||
participant HM as "HotkeyManager.cs"
|
||||
participant Cmd as "YourHotkeyCommand.cs"
|
||||
Boot->>App : Initialize
|
||||
App->>Engine : Start services
|
||||
Engine->>HM : Discover commands via reflection
|
||||
HM-->>Cmd : Instantiate decorated classes
|
||||
HM->>HM : Register command mappings
|
||||
Note over HM,Cmd : Commands are later invoked when user presses bound keys
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
|
||||
**Section sources**
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [HotkeyEntry.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyEntry.cs)
|
||||
|
||||
### Plugin Architecture Guidelines
|
||||
Guidelines for building plugins:
|
||||
- Assembly loading: Place plugin assemblies in the designated directory; the launcher scans for entries compatible with the plugin manifest.
|
||||
- Dependency injection: Use constructor injection where possible; rely on shared services exposed by the engine.
|
||||
- Lifecycle management: Implement initialization and cleanup hooks if needed; ensure thread-safety for background operations.
|
||||
- Manifest and metadata: Provide required metadata so the launcher can enumerate and load your plugin safely.
|
||||
|
||||
Relevant components:
|
||||
- PluginEntry: Represents a plugin manifest entry.
|
||||
- ShardManager: Manages shards and may coordinate plugin loading contexts.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Application Start"]) --> Scan["Scan Plugins Directory"]
|
||||
Scan --> LoadManifest["Load PluginEntry Metadata"]
|
||||
LoadManifest --> Validate{"Valid Manifest?"}
|
||||
Validate --> |No| Skip["Skip Plugin"]
|
||||
Validate --> |Yes| LoadAsm["Load Assembly Safely"]
|
||||
LoadAsm --> DI["Resolve Dependencies"]
|
||||
DI --> Init["Initialize Plugin"]
|
||||
Init --> Run["Run During Session"]
|
||||
Run --> Cleanup["Cleanup on Shutdown"]
|
||||
Cleanup --> End(["Exit"])
|
||||
Skip --> End
|
||||
```
|
||||
|
||||
[No sources needed since this diagram shows conceptual workflow, not actual code structure]
|
||||
|
||||
**Section sources**
|
||||
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
|
||||
- [ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
|
||||
|
||||
### Network Filtering Integration
|
||||
Custom filters can participate in the packet filtering pipeline:
|
||||
- IncomingPacketFilters and OutgoingPacketFilters provide hooks to apply filters to network traffic.
|
||||
- PacketFilter encapsulates core filtering logic and conditions.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
InStart(["Incoming Packet"]) --> ApplyIn["Apply Incoming Filters"]
|
||||
ApplyIn --> DecisionIn{"Filtered?"}
|
||||
DecisionIn --> |Yes| DropIn["Drop Packet"]
|
||||
DecisionIn --> |No| DispatchIn["Dispatch to Handlers"]
|
||||
OutStart(["Outgoing Packet"]) --> ApplyOut["Apply Outgoing Filters"]
|
||||
ApplyOut --> DecisionOut{"Filtered?"}
|
||||
DecisionOut --> |Yes| DropOut["Drop Packet"]
|
||||
DecisionOut --> |No| SendOut["Send Over Network"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
## Dependency Analysis
|
||||
High-level dependencies among extension points:
|
||||
- Filters depend on IConfigurableFilter and FilterEntry for configuration and persistence.
|
||||
- Hotkey commands depend on HotkeyCommandAttribute and HotkeyManager for discovery and dispatch.
|
||||
- Network filters depend on IncomingPacketFilters and OutgoingPacketFilters to integrate with the packet pipeline.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ICF["IConfigurableFilter.cs"] --> FE["FilterEntry.cs"]
|
||||
FOA["FilterOptionsAttribute.cs"] --> FE
|
||||
HCA["HotkeyCommandAttribute.cs"] --> HCM["HotkeyManager.cs"]
|
||||
INPF["IncomingPacketFilters.cs"] --> PF["PacketFilter.cs"]
|
||||
OUTPF["OutgoingPacketFilters.cs"] --> PF
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
**Section sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Keep filter evaluation logic lightweight; avoid heavy allocations and blocking I/O inside hot paths.
|
||||
- Prefer early-exit conditions to minimize processing overhead.
|
||||
- Batch operations where possible and avoid synchronous UI calls from background threads.
|
||||
- For hotkey commands, ensure quick execution; offload long-running tasks to background threads and marshal results back to the UI thread.
|
||||
- Be mindful of memory retention in filter state; release resources promptly.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Filters not appearing in UI:
|
||||
- Verify IConfigurableFilter implementation and FilterEntry registration.
|
||||
- Check FilterOptionsAttribute usage for correct property exposure.
|
||||
- Hotkey commands not firing:
|
||||
- Confirm HotkeyCommandAttribute decoration and proper registration via HotkeyManager.
|
||||
- Ensure no conflicts with existing key bindings.
|
||||
- Network filters not applied:
|
||||
- Validate integration with IncomingPacketFilters and OutgoingPacketFilters.
|
||||
- Inspect PacketFilter conditions and order of application.
|
||||
|
||||
Validation and diagnostics:
|
||||
- Use unit tests to validate filter logic and hotkey command behavior.
|
||||
- Add logging around filter evaluation and command invocation to trace issues.
|
||||
|
||||
**Section sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [HotkeyCommandAttribute.cs](file://ClassicAssist.Shared/Data/Hotkeys/Commands/HotkeyCommandAttribute.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
- [PacketFilter.cs](file://ClassicAssist.Shared/UO/Network/PacketFilter/PacketFilter.cs)
|
||||
|
||||
## Conclusion
|
||||
By implementing IConfigurableFilter and leveraging FilterEntry and FilterOptionsAttribute, you can create robust, configurable message filters. Using HotkeyCommandAttribute and HotkeyManager, you can register custom keyboard shortcuts seamlessly. Follow the plugin architecture guidelines for safe assembly loading, dependency resolution, and lifecycle management. Adhering to performance best practices and security considerations ensures reliable and efficient extensions.
|
||||
|
||||
[No sources needed since this section summarizes without analyzing specific files]
|
||||
|
||||
## Appendices
|
||||
|
||||
### Configuration Schema and Validation Rules
|
||||
- FilterOptionsAttribute drives the schema for filter options.
|
||||
- Define display names, descriptions, value types, and defaults to guide UI rendering and validation.
|
||||
- Persist options via FilterEntry to maintain user preferences across sessions.
|
||||
|
||||
**Section sources**
|
||||
- [FilterOptionsAttribute.cs](file://ClassicAssist.Shared/Data/Filters/FilterOptionsAttribute.cs)
|
||||
- [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs)
|
||||
|
||||
### Testing Strategies
|
||||
- Unit test filter evaluation logic with representative messages.
|
||||
- Mock HotkeyManager interactions to verify command registration and invocation.
|
||||
- Simulate packet flows to validate network filter behavior.
|
||||
|
||||
**Section sources**
|
||||
- [IConfigurableFilter.cs](file://ClassicAssist.Shared/Data/Filters/IConfigurableFilter.cs)
|
||||
- [HotkeyManager.cs](file://ClassicAssist.Shared/Data/Hotkeys/HotkeyManager.cs)
|
||||
- [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs)
|
||||
- [OutgoingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/OutgoingPacketFilters.cs)
|
||||
|
||||
### Security Considerations
|
||||
- Validate all inputs in filters and commands to prevent injection or malformed data issues.
|
||||
- Restrict file system and network access within plugins to necessary scopes.
|
||||
- Avoid executing arbitrary code loaded from untrusted sources; enforce manifest checks and signature verification where applicable.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Distribution Methods for Plugins
|
||||
- Package plugin assemblies with required dependencies.
|
||||
- Include a manifest describing plugin metadata and capabilities.
|
||||
- Distribute via official channels or trusted repositories; ensure users place plugins in the correct directory for discovery.
|
||||
|
||||
**Section sources**
|
||||
- [PluginEntry.cs](file://ClassicAssist.Launcher/PluginEntry.cs)
|
||||
- [ShardManager.cs](file://ClassicAssist.Launcher/ShardManager.cs)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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]
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user