# Chat System **Referenced Files in This Document** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) ## 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 explains the ClassicAssist.Avalonia chat system with a focus on: - The ChatManager class and its role in managing channels, routing messages, and coordinating user interactions - The ChatMessage and ChatUser data models, their properties, relationships, and lifecycle management - The chat window interface implementation for real-time display, channel switching, and input handling - Message filtering capabilities including built-in filters and how to develop custom filters - Integration with Ultima Online’s native chat protocol and packet handling - Configuration options for appearance, notifications, and logging - Performance optimization strategies for high-volume chat processing and memory management ## Project Structure The chat system spans shared logic and UI layers: - Shared domain and networking: - Data models and manager: ChatManager, ChatMessage, ChatUser - UO network integration: IncomingPacketHandlers, IncomingPacketFilters, UnicodeText packet - Filters: FilterEntry and specific filter implementations - Options: Options and AssistantOptions for configuration - Avalonia UI: - Views: ChatWindow.axaml and code-behind - ViewModel: ChatViewModel (shared UI layer) ```mermaid graph TB subgraph "Shared" CM["ChatManager"] MSG["ChatMessage"] USER["ChatUser"] INH["IncomingPacketHandlers"] INF["IncomingPacketFilters"] PKT["UnicodeText Packet"] FENTRY["FilterEntry"] RFILT["RepeatedMessagesFilter"] CFILT["ClilocFilter"] OPTS["Options / AssistantOptions"] end subgraph "Avalonia UI" CWXAML["ChatWindow.axaml"] CWCSD["ChatWindow.xaml.cs"] CVM["ChatViewModel"] end PKT --> INH INH --> CM CM --> MSG CM --> USER CM --> INF INF --> FENTRY FENTRY --> RFILT FENTRY --> CFILT CM --> CVM CVM --> CWXAML CVM --> CWCSD OPTS --> CM OPTS --> CVM ``` **Diagram sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) **Section sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) ## Core Components - ChatManager - Central coordinator for chat channels, message ingestion, filtering, and dispatch to UI - Manages user presence and per-channel state - Integrates with incoming packet handlers and filter pipeline - ChatMessage - Represents a single chat event with metadata such as timestamp, sender, channel, color, and text - Used by both filtering and UI rendering - ChatUser - Represents a player or entity participating in chat - Tracks identity and attributes relevant to chat display and filtering These components collaborate to receive packets, parse them into messages, apply filters, and present results in the chat window. **Section sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) ## Architecture Overview The chat system follows a layered architecture: - Network layer parses UO packets into structured events - Processing layer converts events into ChatMessage instances and applies filters - Presentation layer binds filtered messages to the chat window via a view model ```mermaid sequenceDiagram participant Net as "UO Network" participant InH as "IncomingPacketHandlers" participant Pkt as "UnicodeText Packet" participant CM as "ChatManager" participant Fil as "Filter Pipeline" participant VM as "ChatViewModel" participant Win as "ChatWindow" Net->>InH : "Receive raw packet" InH->>Pkt : "Parse into UnicodeText" Pkt-->>InH : "Parsed packet" InH->>CM : "Dispatch parsed chat event" CM->>CM : "Create ChatMessage" CM->>Fil : "Apply filters" Fil-->>CM : "Filtered result" CM->>VM : "Notify new message" VM->>Win : "Update UI binding" Win-->>VM : "User input / channel switch" VM->>CM : "Forward actions" ``` **Diagram sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) ## Detailed Component Analysis ### ChatManager Responsibilities: - Channel management: creation, selection, and persistence of active channels - Message routing: receiving parsed chat events, constructing ChatMessage objects, applying filters, and notifying observers - User coordination: tracking participants and updating presence information - Configuration integration: reading options for behavior and appearance Key behaviors: - On incoming chat event: - Parse packet fields into ChatMessage - Apply configured filters - Persist or cache recent messages - Raise UI updates through the view model - On user actions: - Handle channel switches and input submission - Update UI state and notify subscribers ```mermaid classDiagram class ChatManager { +SelectChannel(channel) +AddMessage(event) +ApplyFilters(message) +GetActiveChannel() +SubscribeToUpdates(observer) } class ChatMessage { +Timestamp +Sender +Channel +Color +Text } class ChatUser { +Id +Name +Attributes } class FilterPipeline { +Evaluate(message) bool } ChatManager --> ChatMessage : "creates" ChatManager --> ChatUser : "tracks" ChatManager --> FilterPipeline : "uses" ``` **Diagram sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) **Section sources** - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) ### ChatMessage and ChatUser Models ChatMessage: - Properties include timestamp, sender reference, channel identifier, color/hue, and textual content - Lifecycle: created from incoming packets, passed through filters, then bound to UI; may be retained in a bounded buffer for performance ChatUser: - Properties include unique identifier, display name, and optional attributes used for coloring or filtering - Relationship: referenced by ChatMessage to link messages to users ```mermaid erDiagram CHATMESSAGE { datetime Timestamp string SenderId string Channel int Color string Text } CHATUSER { string Id string Name map Attributes } CHATUSER ||--o{ CHATMESSAGE : "sends" ``` **Diagram sources** - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) **Section sources** - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) ### Chat Window Interface (Avalonia) Components: - ChatWindow.axaml defines layout and bindings for message list, channel selector, and input area - ChatWindow.xaml.cs provides code-behind for window behavior and interaction hooks - ChatViewModel coordinates UI state, handles user input, and subscribes to ChatManager updates Workflow: - Real-time display: view model listens for new messages and updates observable collections - Channel switching: view model requests channel change from ChatManager and refreshes display - Input handling: captures user input, validates, and forwards to ChatManager for sending ```mermaid sequenceDiagram participant VM as "ChatViewModel" participant CM as "ChatManager" participant Win as "ChatWindow" Win->>VM : "User types message" VM->>CM : "Submit message" CM-->>VM : "Acknowledge / update state" VM->>Win : "Refresh UI" Win->>VM : "Switch channel" VM->>CM : "Change active channel" CM-->>VM : "Provide channel messages" VM->>Win : "Render channel history" ``` **Diagram sources** - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) **Section sources** - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) - [ChatWindow.xaml.cs](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) ### Message Filtering Capabilities Built-in filters: - RepeatedMessagesFilter: suppresses duplicate or near-duplicate messages based on configurable thresholds - ClilocFilter: matches messages against localized strings for targeted filtering Filter framework: - FilterEntry defines the base contract and configuration surface for filters - IncomingPacketFilters orchestrates evaluation across registered filters Custom filter development: - Implement the filter interface defined by the filter entry base - Provide configuration options via the filter options attribute mechanism - Register the filter with the pipeline so it participates in message evaluation ```mermaid flowchart TD Start(["New ChatMessage"]) --> Eval["Evaluate Filters"] Eval --> Repeat{"RepeatedMessagesFilter?"} Repeat --> |Yes| Drop["Drop message"] Repeat --> |No| Cliloc{"ClilocFilter?"} Cliloc --> |Match| Drop Cliloc --> |No Match| Keep["Keep message"] Drop --> End(["End"]) Keep --> End ``` **Diagram sources** - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) **Section sources** - [FilterEntry.cs](file://ClassicAssist.Shared/Data/Filters/FilterEntry.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) ### Integration with Ultima Online Chat Protocol Packet handling: - IncomingPacketHandlers listen for UO chat-related packets - UnicodeText packet is parsed into structured data and forwarded to ChatManager - ChatManager constructs ChatMessage instances and proceeds through the filter pipeline ```mermaid sequenceDiagram participant UO as "UO Client" participant InH as "IncomingPacketHandlers" participant Pkt as "UnicodeText" participant CM as "ChatManager" UO->>InH : "Send chat packet" InH->>Pkt : "Deserialize packet" Pkt-->>InH : "Structured fields" InH->>CM : "Invoke chat handler" CM->>CM : "Build ChatMessage" ``` **Diagram sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) **Section sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) ### Configuration Options Appearance: - Colors, fonts, and formatting can be controlled via options consumed by the view model and renderer Notifications: - Toggleable notification settings allow users to enable/disable alerts for specific channels or senders Logging: - Logging preferences control verbosity and destinations for chat logs Configuration sources: - Options and AssistantOptions provide strongly-typed settings that are read by ChatManager and ChatViewModel **Section sources** - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) ## Dependency Analysis The chat system exhibits clear separation between networking, processing, and presentation: - Networking depends on UO packet definitions and handlers - Processing depends on data models and filters - Presentation depends on view models and UI controls ```mermaid graph LR InH["IncomingPacketHandlers"] --> Pkt["UnicodeText"] InH --> CM["ChatManager"] CM --> MSG["ChatMessage"] CM --> USER["ChatUser"] CM --> FIL["FilterPipeline"] FIL --> RFILT["RepeatedMessagesFilter"] FIL --> CFILT["ClilocFilter"] CM --> VM["ChatViewModel"] VM --> CW["ChatWindow"] ``` **Diagram sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [UnicodeText.cs](file://ClassicAssist.Shared/UO/Network/Packets/UnicodeText.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatMessage.cs](file://ClassicAssist.Shared/Data/Chat/ChatMessage.cs) - [ChatUser.cs](file://ClassicAssist.Shared/Data/Chat/ChatUser.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [RepeatedMessagesFilter.cs](file://ClassicAssist.Shared/Data/Filters/RepeatedMessagesFilter.cs) - [ClilocFilter.cs](file://ClassicAssist.Shared/Data/Filters/ClilocFilter.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) - [ChatWindow.xaml](file://ClassicAssist.Avalonia/Views/ChatWindow.xaml) **Section sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [ChatManager.cs](file://ClassicAssist.Shared/Data/Chat/ChatManager.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) ## Performance Considerations High-volume chat processing requires careful attention to throughput and memory usage: - Bounded message buffers: limit retained messages to reduce memory pressure while preserving recent history - Efficient filtering: short-circuit filters when possible and avoid heavy allocations inside hot paths - UI batching: coalesce UI updates to minimize layout passes and redraws - Thread affinity: ensure UI updates occur on the UI thread using the dispatcher provided by the platform - Garbage collection: reuse objects where feasible and avoid unnecessary string allocations [No sources needed since this section provides general guidance] ## Troubleshooting Guide Common issues and resolutions: - Messages not appearing: - Verify incoming packet handlers are registered and parsing UnicodeText correctly - Check filter pipeline configuration to ensure messages are not being dropped unintentionally - Incorrect colors or formatting: - Confirm options for appearance are applied consistently in the view model and renderer - High CPU usage during chat spikes: - Review filter complexity and consider simplifying conditions - Ensure UI updates are batched and not triggered excessively **Section sources** - [IncomingPacketHandlers.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketHandlers.cs) - [IncomingPacketFilters.cs](file://ClassicAssist.Shared/UO/Network/IncomingPacketFilters.cs) - [ChatViewModel.cs](file://ClassicAssist/UI/ViewModels/ChatViewModel.cs) ## Conclusion The ClassicAssist.Avalonia chat system integrates tightly with Ultima Online’s packet protocol, providing robust channel management, flexible filtering, and responsive UI. By leveraging well-defined data models and a modular filter pipeline, it supports both built-in and custom filtering scenarios. Configuration options allow tailoring appearance, notifications, and logging. For high-volume environments, adopting bounded buffers, efficient filtering, and UI batching ensures smooth performance and stable memory usage.