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